@naisys/common 3.0.0-beta.10

package/dist/agentConfigFile.js

@@ -0,0 +1,129 @@
+import { z } from "zod";
+import { TARGET_MEGAPIXELS } from "./constants.js";
+import { URL_SAFE_KEY_MESSAGE, URL_SAFE_KEY_REGEX } from "./urlSafeKey.js";
+export const commandProtectionValues = [
+    "none",
+    "manual",
+    "semi-auto",
+    "auto",
+];
+// Zod schema for validation
+export const AgentConfigFileSchema = z.object({
+    username: z
+        .string()
+        .min(1, "Username is required")
+        .regex(URL_SAFE_KEY_REGEX, URL_SAFE_KEY_MESSAGE)
+        .describe("The name the agent identifies itself with when communicating with other agents"),
+    title: z
+        .string()
+        .describe("Displayed to other agents to give context about this agent's role in the system"),
+    agentPrompt: z
+        .string()
+        .min(1, "Agent prompt is required")
+        .describe("Gives the agent instructions and/or purpose when starting up. Supports ${agent.*} and ${env.*} template variables"),
+    spendLimitDollars: z
+        .number()
+        .min(0, "Must be non-negative")
+        .optional()
+        .describe("Spend limit in dollars for this agent. When set, this agent is exempt from the global spend limit. Defaults to the SPEND_LIMIT_DOLLARS variable"),
+    spendLimitHours: z
+        .number()
+        .min(0, "Must be non-negative")
+        .optional()
+        .describe("Rolling time window in hours for spend limit, defaults to the SPEND_LIMIT_HOURS variable. If neither are set then the spend limit is fixed and not rolling"),
+    tokenMax: z
+        .number()
+        .int("Must be a whole number")
+        .min(1, "Must be at least 1")
+        .describe("How many tokens this agent is allocated per session before it must end or compact the context"),
+    shellModel: z
+        .string()
+        .min(1, "Shell model is required")
+        .describe("Primary LLM used for shell interactions"),
+    imageModel: z.string().optional().describe("Model used for image generation"),
+    mailEnabled: z
+        .boolean()
+        .optional()
+        .describe("Show mail commands to the agent. Mail encourages verbose communication which can be distracting"),
+    chatEnabled: z
+        .boolean()
+        .optional()
+        .describe("Show chat commands to the agent. Chat encourages more concise communication"),
+    webEnabled: z
+        .boolean()
+        .optional()
+        .describe("Allow agent to browse the web with Lynx, a text based browser"),
+    completeSessionEnabled: z
+        .boolean()
+        .optional()
+        .describe("Allow the agent to end its session. Once ended, it can only be restarted explicitly or via mail if wakeOnMessage is enabled. Disable on root agents to prevent the system from going unresponsive"),
+    debugPauseSeconds: z
+        .number()
+        .int("Must be a whole number")
+        .min(0, "Must be non-negative")
+        .optional()
+        .describe("Seconds to wait at the debug prompt before auto-continuing, only applies when the agent's console is in focus. Unset waits indefinitely for manual input"),
+    wakeOnMessage: z
+        .boolean()
+        .optional()
+        .describe("When mail or chat is received, start the agent automatically, or wake it from its wait state"),
+    commandProtection: z
+        .enum(commandProtectionValues)
+        .optional()
+        .describe("None allows the LLM to run any command, Manual requires user confirmation for each command, and Auto uses a secondary LLM to try to validate a command is safe"),
+    initialCommands: z
+        .array(z.string())
+        .optional()
+        .describe("Shell commands to run at session start before the first LLM prompt, providing additional context to the agent"),
+    multipleCommandsEnabled: z
+        .boolean()
+        .optional()
+        .describe("Allow the LLM to run multiple commands per turn. Faster but the LLM may get ahead of itself and produce errors"),
+    workspacesEnabled: z
+        .boolean()
+        .optional()
+        .describe("Experimental: Allows the LLM to pin files to the end of the context. Each turn the agent sees the latest version without old versions taking up context space"),
+    controlDesktop: z
+        .boolean()
+        .optional()
+        .describe(`Allow the agent to operate the desktop GUI. Requires a model with supportsComputerUse. Ideal screen resolution <= ${TARGET_MEGAPIXELS}MP to avoid downscaling`),
+});
+/**
+ * Thoughts on the admin user:
+ * 1. We need an admin user as a placeholder when no agents are running
+ *    Especially when a hub client starts up and the hub has assigned no agents to the host
+ * 2. We want to be able to start agents and send mail from the placeholder so it needs to be an official user
+ *    It is registered in the hub db as well so we don't need tons of special case code everywhere like `if (userId === adminUserId)` ...
+ * 3. The admin is also a source of ns-talk commands, gives the LLM someone to reply to
+ * 4. Calling it a debug user would be confusing with debug input mode, also considered calling it operator, but admin seems more intuitive
+ * 5. The hub supports agents running simultaneously across hosts, so each client can run an admin fine
+ * 6. Having it as an official user means mail will be logged by the hub as well which is helpful for debugging and monitoring
+ */
+export function buildDefaultAgentConfig(username) {
+    return {
+        username,
+        title: "Assistant",
+        shellModel: "none",
+        agentPrompt: "You are ${agent.username} a ${agent.title} with the job of helping out the admin with what they want to do.",
+        tokenMax: 20000,
+        debugPauseSeconds: 5,
+        mailEnabled: true,
+        chatEnabled: true,
+        webEnabled: true,
+        wakeOnMessage: true,
+        completeSessionEnabled: true,
+        multipleCommandsEnabled: true,
+    };
+}
+export const adminAgentConfig = {
+    username: "admin", // Must be "admin" for special handling in hub and supervisor
+    title: "Admin",
+    shellModel: "none",
+    agentPrompt: "Human admin for monitoring and control.",
+    tokenMax: 100_000,
+    mailEnabled: true,
+    chatEnabled: true,
+    wakeOnMessage: true,
+    webEnabled: true,
+    spendLimitDollars: 1, // Required on all agents
+};

package/dist/agentStatus.js

@@ -0,0 +1,15 @@
+export function determineAgentStatus(opts) {
+    // Priority: disabled > offline > suspended > active > available
+    if (!opts.isEnabled)
+        return "disabled";
+    const isOffline = opts.assignedHostIds?.length
+        ? !opts.assignedHostIds.some(opts.isHostOnline)
+        : !opts.hasNonRestrictedOnlineHost;
+    if (isOffline)
+        return "offline";
+    if (opts.isSuspended)
+        return "suspended";
+    if (opts.isActive)
+        return "active";
+    return "available";
+}

package/dist/authCache.js

@@ -0,0 +1,41 @@
+export class AuthCache {
+    cache = new Map();
+    ttlMs;
+    negativeTtlMs;
+    maxSize;
+    constructor(options = {}) {
+        this.ttlMs = options.ttlMs ?? 60_000;
+        this.negativeTtlMs = options.negativeTtlMs ?? 10_000;
+        this.maxSize = options.maxSize ?? 1_000;
+    }
+    /** Returns the cached user, `null` for a negative hit, or `undefined` on cache miss. */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        return entry.user;
+    }
+    /** Cache a lookup result. Pass `null` to cache a negative (invalid token) result. */
+    set(key, user) {
+        if (this.cache.size >= this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            this.cache.delete(firstKey);
+        }
+        this.cache.set(key, {
+            user,
+            expiresAt: Date.now() + (user ? this.ttlMs : this.negativeTtlMs),
+        });
+    }
+    /** Remove a specific key from the cache (e.g. on logout). */
+    invalidate(key) {
+        this.cache.delete(key);
+    }
+    /** Clear the entire cache. */
+    clear() {
+        this.cache.clear();
+    }
+}

package/dist/builtInModels.js

@@ -0,0 +1,260 @@
+import { LlmApiType } from "./modelTypes.js";
+// --- Built-in LLM models ---
+// Prices are per 1M tokens in USD. Last updated: February 2026.
+export const builtInLlmModels = [
+    {
+        key: LlmApiType.None,
+        label: "None",
+        versionName: LlmApiType.None,
+        apiType: LlmApiType.None,
+        apiKeyVar: "",
+        maxTokens: 10_000,
+        inputCost: 0,
+        outputCost: 0,
+    },
+    {
+        key: LlmApiType.Mock,
+        label: "Mock",
+        versionName: LlmApiType.Mock,
+        apiType: LlmApiType.Mock,
+        apiKeyVar: "",
+        maxTokens: 10_000,
+        inputCost: 0,
+        outputCost: 0,
+    },
+    // ── Open Router ──────────────────────────────────────────────────────
+    {
+        key: "llama4",
+        label: "Llama 4 Maverick",
+        versionName: "meta-llama/llama-4-maverick",
+        baseUrl: "https://openrouter.ai/api/v1",
+        apiType: LlmApiType.OpenAI,
+        apiKeyVar: "OPENROUTER_API_KEY",
+        maxTokens: 1_000_000,
+        inputCost: 0.15,
+        outputCost: 0.6,
+        supportsVision: true,
+    },
+    // ── xAI / Grok ──────────────────────────────────────────────────────
+    // https://docs.x.ai/developers/models
+    {
+        key: "grok4",
+        label: "Grok 4",
+        versionName: "grok-4",
+        baseUrl: "https://api.x.ai/v1",
+        apiType: LlmApiType.OpenAI,
+        apiKeyVar: "XAI_API_KEY",
+        maxTokens: 256_000,
+        inputCost: 3,
+        outputCost: 15,
+        cacheWriteCost: 0.75,
+        cacheReadCost: 0.75,
+        cacheTtlSeconds: 300,
+        supportsVision: true,
+    },
+    {
+        key: "grok4fast",
+        label: "Grok 4.1 Fast",
+        versionName: "grok-4.1-fast",
+        baseUrl: "https://api.x.ai/v1",
+        apiType: LlmApiType.OpenAI,
+        apiKeyVar: "XAI_API_KEY",
+        maxTokens: 2_000_000,
+        inputCost: 0.2,
+        outputCost: 0.5,
+        cacheWriteCost: 0.05,
+        cacheReadCost: 0.05,
+        cacheTtlSeconds: 300,
+        supportsVision: true,
+    },
+    // ── OpenAI Models ────────────────────────────────────────────────────
+    // https://openai.com/api/pricing/
+    {
+        key: "gpt5",
+        label: "GPT 5.4",
+        versionName: "gpt-5.4",
+        apiType: LlmApiType.OpenAI,
+        apiKeyVar: "OPENAI_API_KEY",
+        maxTokens: 400_000,
+        inputCost: 2.5,
+        outputCost: 15.0,
+        cacheWriteCost: 0.25,
+        cacheReadCost: 0.25,
+        cacheTtlSeconds: 300,
+        supportsVision: true,
+        supportsComputerUse: true,
+    },
+    {
+        key: "gpt5mini",
+        label: "GPT 5 Mini",
+        versionName: "gpt-5-mini",
+        apiType: LlmApiType.OpenAI,
+        apiKeyVar: "OPENAI_API_KEY",
+        maxTokens: 400_000,
+        inputCost: 0.25,
+        outputCost: 2.0,
+        cacheWriteCost: 0.025,
+        cacheReadCost: 0.025,
+        cacheTtlSeconds: 300,
+        supportsVision: true,
+    },
+    {
+        key: "gpt5nano",
+        label: "GPT 5 Nano",
+        versionName: "gpt-5-nano",
+        apiType: LlmApiType.OpenAI,
+        apiKeyVar: "OPENAI_API_KEY",
+        maxTokens: 400_000,
+        inputCost: 0.05,
+        outputCost: 0.4,
+        cacheWriteCost: 0.005,
+        cacheReadCost: 0.005,
+        cacheTtlSeconds: 300,
+        supportsVision: true,
+    },
+    // ── Google Models ────────────────────────────────────────────────────
+    // https://ai.google.dev/gemini-api/docs/pricing
+    {
+        key: "gemini3pro",
+        label: "Gemini 3.1 Pro",
+        versionName: "gemini-3.1-pro-preview",
+        apiType: LlmApiType.Google,
+        apiKeyVar: "GOOGLE_API_KEY",
+        maxTokens: 2_000_000,
+        inputCost: 2.0,
+        outputCost: 12.0,
+        cacheWriteCost: 0.2,
+        cacheReadCost: 0.2,
+        cacheTtlSeconds: 300,
+        supportsVision: true,
+        supportsHearing: true,
+    },
+    {
+        key: "gemini3flash",
+        label: "Gemini 3 Flash",
+        versionName: "gemini-3-flash-preview",
+        apiType: LlmApiType.Google,
+        apiKeyVar: "GOOGLE_API_KEY",
+        maxTokens: 1_000_000,
+        inputCost: 0.5,
+        outputCost: 3.0,
+        cacheWriteCost: 0.05,
+        cacheReadCost: 0.05,
+        cacheTtlSeconds: 300,
+        supportsVision: true,
+        supportsHearing: true,
+        supportsComputerUse: true,
+    },
+    {
+        key: "gemini2pro",
+        label: "Gemini 2 Pro",
+        versionName: "gemini-2.5-computer-use-preview-10-2025",
+        apiType: LlmApiType.Google,
+        apiKeyVar: "GOOGLE_API_KEY",
+        maxTokens: 2_000_000,
+        inputCost: 2.0,
+        outputCost: 12.0,
+        cacheWriteCost: 0.2,
+        cacheReadCost: 0.2,
+        cacheTtlSeconds: 300,
+        supportsVision: true,
+        supportsHearing: true,
+        supportsComputerUse: true,
+    },
+    // ── Anthropic Models ─────────────────────────────────────────────────
+    // https://platform.claude.com/docs/en/about-claude/pricing
+    // Cache: 5m write = 1.25× input, read = 0.1× input
+    {
+        key: "claude4opus",
+        label: "Claude Opus 4.6",
+        versionName: "claude-opus-4-6",
+        apiType: LlmApiType.Anthropic,
+        apiKeyVar: "ANTHROPIC_API_KEY",
+        maxTokens: 200_000,
+        inputCost: 5,
+        outputCost: 25,
+        cacheWriteCost: 6.25,
+        cacheReadCost: 0.5,
+        cacheTtlSeconds: 300,
+        supportsVision: true,
+        supportsComputerUse: true,
+    },
+    {
+        key: "claude4sonnet",
+        label: "Claude Sonnet 4.6",
+        versionName: "claude-sonnet-4-6",
+        apiType: LlmApiType.Anthropic,
+        apiKeyVar: "ANTHROPIC_API_KEY",
+        maxTokens: 200_000,
+        inputCost: 3,
+        outputCost: 15,
+        cacheWriteCost: 3.75,
+        cacheReadCost: 0.3,
+        cacheTtlSeconds: 300,
+        supportsVision: true,
+        supportsComputerUse: true,
+    },
+    {
+        key: "claude4haiku",
+        label: "Claude Haiku 4.5",
+        versionName: "claude-haiku-4-5",
+        apiType: LlmApiType.Anthropic,
+        apiKeyVar: "ANTHROPIC_API_KEY",
+        maxTokens: 200_000,
+        inputCost: 1,
+        outputCost: 5,
+        cacheWriteCost: 1.25,
+        cacheReadCost: 0.1,
+        cacheTtlSeconds: 300,
+        supportsVision: true,
+        supportsComputerUse: true,
+    },
+];
+// --- Built-in image models ---
+// Costs are approximate per-image for 1024x1024.
+export const builtInImageModels = [
+    {
+        key: "gptimage1high",
+        label: "GPT Image 1.5 High",
+        versionName: "gpt-image-1.5",
+        size: "1024x1024",
+        apiKeyVar: "OPENAI_API_KEY",
+        quality: "high",
+        cost: 0.17,
+    },
+    {
+        key: "gptimage1medium",
+        label: "GPT Image 1.5 Medium",
+        versionName: "gpt-image-1.5",
+        size: "1024x1024",
+        apiKeyVar: "OPENAI_API_KEY",
+        quality: "medium",
+        cost: 0.04,
+    },
+    {
+        key: "gptimage1low",
+        label: "GPT Image 1.5 Low",
+        versionName: "gpt-image-1.5",
+        size: "1024x1024",
+        apiKeyVar: "OPENAI_API_KEY",
+        quality: "low",
+        cost: 0.01,
+    },
+    {
+        key: "dalle3-1024-HD",
+        label: "DALL-E 3 1024 HD",
+        versionName: "dall-e-3",
+        size: "1024x1024",
+        apiKeyVar: "OPENAI_API_KEY",
+        quality: "hd",
+        cost: 0.08,
+    },
+    {
+        key: "dalle3-1024",
+        label: "DALL-E 3 1024",
+        versionName: "dall-e-3",
+        size: "1024x1024",
+        apiKeyVar: "OPENAI_API_KEY",
+        cost: 0.04,
+    },
+];

package/dist/configUtils.js

@@ -0,0 +1,9 @@
+export function sanitizeSpendLimit(num) {
+    if (num === undefined)
+        return undefined;
+    const n = Number(num);
+    if (isNaN(n) || n <= 0) {
+        return undefined;
+    }
+    return n;
+}

package/dist/constants.js

@@ -0,0 +1,4 @@
+export const SUPER_ADMIN_USERNAME = "superadmin";
+export const NAV_HEADER_ROW_HEIGHT = 48;
+/** Target megapixels for screenshots sent to LLMs during computer use */
+export const TARGET_MEGAPIXELS = 1.1;

package/dist/costUtils.js

@@ -0,0 +1,23 @@
+/**
+ * Calculate the current period boundaries based on a given number of hours.
+ * Periods are fixed multiples of hours from midnight (server local time).
+ * The reason we don't slide the window is that we don't want to the llm to get stuck sending off a query
+ * only for the window to close again, and the llm cache to *expire* creating a cycle of constant cache misses
+ */
+export function calculatePeriodBoundaries(hours) {
+    const now = new Date();
+    // Get midnight of current day in local time
+    const midnight = new Date(now);
+    midnight.setHours(0, 0, 0, 0);
+    // Calculate milliseconds since midnight
+    const msSinceMidnight = now.getTime() - midnight.getTime();
+    const hoursSinceMidnight = msSinceMidnight / (1000 * 60 * 60);
+    // Calculate which period we're in (0, 1, 2, ...)
+    const periodIndex = Math.floor(hoursSinceMidnight / hours);
+    // Calculate period start and end
+    const periodStartHours = periodIndex * hours;
+    const periodEndHours = (periodIndex + 1) * hours;
+    const periodStart = new Date(midnight.getTime() + periodStartHours * 60 * 60 * 1000);
+    const periodEnd = new Date(midnight.getTime() + periodEndHours * 60 * 60 * 1000);
+    return { periodStart, periodEnd };
+}

package/dist/errorHandler.js

@@ -0,0 +1,44 @@
+/**
+ * Shared Fastify error handler that bypasses route-level Zod response
+ * serializers by sending a pre-stringified JSON payload.  Without this,
+ * an error whose shape doesn't match the route's response schema causes a
+ * cascading "Failed to serialize an error" from fastify-type-provider-zod.
+ *
+ * Interfaces are duck-typed so @naisys/common doesn't need a Fastify dependency.
+ */
+function errorLabel(statusCode) {
+    switch (statusCode) {
+        case 400:
+            return "Bad Request";
+        case 401:
+            return "Unauthorized";
+        case 403:
+            return "Forbidden";
+        case 404:
+            return "Not Found";
+        case 409:
+            return "Conflict";
+        default:
+            return statusCode >= 500 ? "Internal Server Error" : "Error";
+    }
+}
+export function commonErrorHandler(error, request, reply) {
+    let statusCode = error.statusCode ?? 500;
+    let message = error.message;
+    // Prisma unique-constraint violation → 409 Conflict
+    if (error.name === "PrismaClientKnownRequestError" &&
+        error.code === "P2002") {
+        statusCode = 409;
+        message = "A record with that unique value already exists";
+    }
+    request.log.error({ err: error, url: request.url, method: request.method }, "Request error");
+    // Pre-stringify to bypass the route's Zod response serializer
+    reply
+        .status(statusCode)
+        .header("content-type", "application/json; charset=utf-8")
+        .send(JSON.stringify({
+        statusCode,
+        error: errorLabel(statusCode),
+        message,
+    }));
+}

package/dist/formatFileSize.js

@@ -0,0 +1,10 @@
+/** Maximum allowed file size for attachments (10 MB) */
+export const MAX_ATTACHMENT_SIZE = 10 * 1024 * 1024;
+/** Format a byte count into a human-readable size string (e.g. "1.2 KB") */
+export function formatFileSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

package/dist/globalConfigLoader.js

@@ -0,0 +1,58 @@
+import { sanitizeSpendLimit } from "./configUtils.js";
+/** Keys that should never be distributed to clients */
+const EXCLUDED_KEYS = [
+    "HUB_ACCESS_KEY",
+    "HUB_PORT",
+    "NAISYS_FOLDER",
+    "NAISYS_HOSTNAME",
+    "NODE_ENV",
+    "SUPERVISOR_PORT",
+];
+/**
+ * Builds hub-distributable config from the provided env vars.
+ * @param variables - Env var source: process.env (ephemeral) or DB-sourced map (hub).
+ * @param shellExportKeys - Set of variable keys that should be exported to the shell.
+ *   When undefined (e.g. .env fallback), all variables are exported for backwards compat.
+ */
+export function buildClientConfig(variables, shellExportKeys) {
+    const shellCommand = {
+        outputTokenMax: 7500,
+        timeoutSeconds: 10,
+        maxTimeoutSeconds: 60 * 5,
+    };
+    const retrySecondsMax = 30 * 60;
+    const webTokenMax = 5000;
+    const compactSessionEnabled = true;
+    const preemptiveCompactEnabled = true;
+    // Build variableMap, filtering out excluded keys and undefined values
+    const variableMap = {};
+    const shellVariableMap = {};
+    for (const [key, value] of Object.entries(variables)) {
+        if (value !== undefined && !EXCLUDED_KEYS.includes(key)) {
+            variableMap[key] = value;
+            // When shellExportKeys is undefined (standalone .env mode), export all
+            if (!shellExportKeys || shellExportKeys.has(key)) {
+                shellVariableMap[key] = value;
+            }
+        }
+    }
+    const googleSearchEngineId = variableMap.GOOGLE_SEARCH_ENGINE_ID;
+    const spendLimitDollars = sanitizeSpendLimit(variableMap.SPEND_LIMIT_DOLLARS);
+    const spendLimitHours = sanitizeSpendLimit(variableMap.SPEND_LIMIT_HOURS);
+    const useToolsForLlmConsoleResponses = true;
+    const autoStartAgentsOnMessage = true;
+    return {
+        shellCommand,
+        retrySecondsMax,
+        webTokenMax,
+        compactSessionEnabled,
+        preemptiveCompactEnabled,
+        variableMap,
+        shellVariableMap,
+        googleSearchEngineId,
+        spendLimitDollars,
+        spendLimitHours,
+        useToolsForLlmConsoleResponses,
+        autoStartAgentsOnMessage,
+    };
+}

package/dist/hateoas-types.js

@@ -0,0 +1,42 @@
+import { z } from "zod/v4";
+export const HateoasLinkSchema = z.object({
+    rel: z.string(),
+    href: z.string(),
+    method: z.string().optional(),
+    title: z.string().optional(),
+    schema: z.string().optional(),
+});
+export const AlternateEncodingSchema = z.object({
+    contentType: z.string(),
+    description: z.string().optional(),
+    fileFields: z.array(z.string()),
+});
+export const HateoasActionSchema = z.object({
+    rel: z.string(),
+    href: z.string(),
+    method: z.string(),
+    title: z.string().optional(),
+    schema: z.string().optional(),
+    body: z.record(z.string(), z.unknown()).optional(),
+    alternateEncoding: AlternateEncodingSchema.optional(),
+    disabled: z.boolean().optional(),
+    disabledReason: z.union([z.string(), z.array(z.string())]).optional(),
+});
+export const HateoasActionTemplateSchema = z.object({
+    rel: z.string(),
+    hrefTemplate: z.string(),
+    method: z.string(),
+    title: z.string().optional(),
+    schema: z.string().optional(),
+    body: z.record(z.string(), z.unknown()).optional(),
+    alternateEncoding: AlternateEncodingSchema.optional(),
+});
+export const HateoasLinkTemplateSchema = z.object({
+    rel: z.string(),
+    hrefTemplate: z.string(),
+    title: z.string().optional(),
+});
+export const HateoasLinksSchema = z.object({
+    _links: z.array(HateoasLinkSchema),
+    _actions: z.array(HateoasActionSchema).optional(),
+});

package/dist/hateoas.js

@@ -0,0 +1,66 @@
+/**
+ * Returns the action if it exists and is enabled.
+ * Pass `{ includeDisabled: true }` to also return disabled actions
+ * (e.g. when rendering a disabled button with a tooltip).
+ */
+export function hasAction(actions, rel, opts) {
+    const a = actions?.find((a) => a.rel === rel);
+    if (!a)
+        return undefined;
+    if (a.disabled && !opts?.includeDisabled)
+        return undefined;
+    return a;
+}
+export function hasActionTemplate(templates, rel) {
+    return templates?.find((t) => t.rel === rel);
+}
+export function hasLinkTemplate(templates, rel) {
+    return templates?.find((t) => t.rel === rel);
+}
+export function resolveActions(defs, baseHref, ctx, checkPermission) {
+    const actions = [];
+    for (const def of defs) {
+        if (def.statuses) {
+            const status = ctx.status;
+            if (!status || !def.statuses.includes(status))
+                continue;
+        }
+        if (def.visibleWhen && !def.visibleWhen(ctx))
+            continue;
+        const hasPerm = !def.permission || checkPermission(def.permission);
+        if (def.hideWithoutPermission && !hasPerm)
+            continue;
+        const gate = !hasPerm && def.permission
+            ? {
+                disabled: true,
+                disabledReason: `Requires ${def.permission} permission`,
+            }
+            : {};
+        const disabledReason = hasPerm && def.disabledWhen ? def.disabledWhen(ctx) : null;
+        actions.push({
+            rel: def.rel,
+            href: def.href ?? baseHref + (def.path ?? ""),
+            method: def.method,
+            title: def.title,
+            ...(def.schema ? { schema: def.schema } : {}),
+            ...(def.body ? { body: def.body } : {}),
+            ...gate,
+            ...(disabledReason ? { disabled: true, disabledReason } : {}),
+        });
+    }
+    return actions;
+}
+export function permGate(hasPerm, permission) {
+    return hasPerm
+        ? {}
+        : {
+            disabled: true,
+            disabledReason: `Requires ${permission} permission`,
+        };
+}
+/** Normalize a `disabledReason` (string | string[] | undefined) to a single display string. */
+export function formatDisabledReason(reason) {
+    if (!reason)
+        return undefined;
+    return Array.isArray(reason) ? reason.join("\n") : reason;
+}

package/dist/hostedServices.js

@@ -0,0 +1,8 @@
+/**
+ * Interfaces for services that can be dynamically loaded in "hosted" mode
+ * (running in the same process space to save memory).
+ *
+ * These are defined in @naisys/common so that both the caller and implementer
+ * share the same type without a compile-time dependency between them.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,19 @@
+export * from "./agentConfigFile.js";
+export * from "./agentStatus.js";
+export * from "./authCache.js";
+export * from "./builtInModels.js";
+export * from "./configUtils.js";
+export * from "./constants.js";
+export * from "./costUtils.js";
+export * from "./errorHandler.js";
+export * from "./formatFileSize.js";
+export * from "./globalConfigLoader.js";
+export * from "./hateoas.js";
+export * from "./hateoas-types.js";
+export * from "./hostedServices.js";
+export * from "./lenientJsonParser.js";
+export * from "./mimeTypes.js";
+export * from "./modelTypes.js";
+export * from "./securityHeaders.js";
+export * from "./sleep.js";
+export * from "./urlSafeKey.js";

package/dist/lenientJsonParser.js

@@ -0,0 +1,19 @@
+/**
+ * Custom JSON content-type parser that accepts empty bodies on POST endpoints.
+ * Without this, sending Content-Type: application/json with no body (common
+ * with HTTP clients calling bodiless state-transition actions like /start,
+ * /complete) causes a JSON parse error.
+ *
+ * Interface is duck-typed so @naisys/common doesn't need a Fastify dependency.
+ */
+export function registerLenientJsonParser(fastify) {
+    fastify.addContentTypeParser("application/json", { parseAs: "string" }, (_req, body, done) => {
+        try {
+            done(null, body.length > 0 ? JSON.parse(body) : {});
+        }
+        catch (err) {
+            err.statusCode = 400;
+            done(err, undefined);
+        }
+    });
+}

package/dist/mimeTypes.js

@@ -0,0 +1,25 @@
+const MIME_TYPES = {
+    // Images
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".bmp": "image/bmp",
+    // Audio
+    ".wav": "audio/wav",
+    ".mp3": "audio/mpeg",
+    ".m4a": "audio/mp4",
+    ".flac": "audio/flac",
+    ".ogg": "audio/ogg",
+    ".webm": "audio/webm",
+    // Documents
+    ".pdf": "application/pdf",
+    ".txt": "text/plain",
+    ".json": "application/json",
+};
+export function mimeFromFilename(filename) {
+    const ext = filename.slice(filename.lastIndexOf(".")).toLowerCase();
+    return MIME_TYPES[ext] ?? "application/octet-stream";
+}

package/dist/modelTypes.js

@@ -0,0 +1,142 @@
+import { z } from "zod";
+import { builtInImageModels, builtInLlmModels } from "./builtInModels.js";
+// --- Enums ---
+export var LlmApiType;
+(function (LlmApiType) {
+    LlmApiType["OpenAI"] = "openai";
+    LlmApiType["Google"] = "google";
+    LlmApiType["Anthropic"] = "anthropic";
+    LlmApiType["Mock"] = "mock";
+    LlmApiType["None"] = "none";
+})(LlmApiType || (LlmApiType = {}));
+// --- Model schemas ---
+export const LlmModelSchema = z
+    .object({
+    key: z.string().min(1),
+    label: z.string().min(1),
+    versionName: z.string().min(1),
+    apiType: z.enum(LlmApiType),
+    maxTokens: z.number().int().positive(),
+    baseUrl: z.string().optional(),
+    apiKeyVar: z.string(),
+    inputCost: z.number().default(0),
+    outputCost: z.number().default(0),
+    cacheWriteCost: z.number().optional(),
+    cacheReadCost: z.number().optional(),
+    cacheTtlSeconds: z.number().int().positive().optional(),
+    supportsVision: z.boolean().optional(),
+    supportsHearing: z.boolean().optional(),
+    supportsComputerUse: z.boolean().optional(),
+})
+    .superRefine((data, ctx) => {
+    if (data.baseUrl &&
+        ![LlmApiType.OpenAI, LlmApiType.Anthropic, LlmApiType.Google].includes(data.apiType)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `baseUrl is only supported for OpenAI, Anthropic, and Google API types (got "${data.apiType}")`,
+            path: ["baseUrl"],
+        });
+    }
+});
+export const ImageModelSchema = z.object({
+    key: z.string().min(1),
+    label: z.string().min(1),
+    versionName: z.string().min(1),
+    size: z.string().min(1),
+    baseUrl: z.string().optional(),
+    apiKeyVar: z.string(),
+    cost: z.number(),
+    quality: z.enum(["standard", "hd", "high", "medium", "low"]).optional(),
+});
+// --- Custom models file schema ---
+export const CustomModelsFileSchema = z.object({
+    llmModels: z.array(LlmModelSchema).optional(),
+    imageModels: z.array(ImageModelSchema).optional(),
+});
+// --- DB meta schemas (for JSON stored in models.meta column) ---
+const LlmMetaSchema = z.object({
+    apiType: z.enum(LlmApiType),
+    maxTokens: z.number().int().positive(),
+    baseUrl: z.string().optional(),
+    apiKeyVar: z.string(),
+    inputCost: z.number().default(0),
+    outputCost: z.number().default(0),
+    cacheWriteCost: z.number().optional(),
+    cacheReadCost: z.number().optional(),
+    cacheTtlSeconds: z.number().int().positive().optional(),
+    supportsVision: z.boolean().optional(),
+    supportsHearing: z.boolean().optional(),
+    supportsComputerUse: z.boolean().optional(),
+});
+const ImageMetaSchema = z.object({
+    size: z.string().min(1),
+    baseUrl: z.string().optional(),
+    apiKeyVar: z.string(),
+    cost: z.number(),
+    quality: z.enum(["standard", "hd", "high", "medium", "low"]).optional(),
+});
+export function llmModelToDbFields(model, isBuiltin, isCustom) {
+    const { key, label, versionName, ...metaFields } = model;
+    return {
+        key,
+        type: "llm",
+        label,
+        version_name: versionName,
+        is_builtin: isBuiltin,
+        is_custom: isCustom,
+        meta: JSON.stringify(metaFields),
+    };
+}
+export function imageModelToDbFields(model, isBuiltin, isCustom) {
+    const { key, label, versionName, ...metaFields } = model;
+    return {
+        key,
+        type: "image",
+        label,
+        version_name: versionName,
+        is_builtin: isBuiltin,
+        is_custom: isCustom,
+        meta: JSON.stringify(metaFields),
+    };
+}
+export function dbFieldsToLlmModel(row) {
+    const meta = LlmMetaSchema.parse(JSON.parse(row.meta));
+    return {
+        key: row.key,
+        label: row.label,
+        versionName: row.version_name,
+        ...meta,
+    };
+}
+export function dbFieldsToImageModel(row) {
+    const meta = ImageMetaSchema.parse(JSON.parse(row.meta));
+    return {
+        key: row.key,
+        label: row.label,
+        versionName: row.version_name,
+        ...meta,
+    };
+}
+// --- Merge helpers ---
+function mergeModels(builtIn, custom) {
+    if (!custom || custom.length === 0) {
+        return [...builtIn];
+    }
+    const result = [...builtIn];
+    for (const c of custom) {
+        const idx = result.findIndex((m) => m.key === c.key);
+        if (idx >= 0) {
+            result[idx] = c;
+        }
+        else {
+            result.push(c);
+        }
+    }
+    return result;
+}
+export function getAllLlmModels(customLlmModels) {
+    return mergeModels(builtInLlmModels, customLlmModels);
+}
+export function getAllImageModels(customImageModels) {
+    return mergeModels(builtInImageModels, customImageModels);
+}

package/dist/securityHeaders.js

@@ -0,0 +1,21 @@
+/**
+ * Shared security-header hook for Fastify servers.
+ *
+ * Interfaces are duck-typed so @naisys/common doesn't need a Fastify dependency.
+ */
+export function registerSecurityHeaders(fastify, options) {
+    const strictCsp = "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; connect-src 'self' ws: wss:; font-src 'self' data:; frame-ancestors 'none'";
+    // Scalar API reference needs inline scripts, eval (bundled Zod JIT),
+    // CDN assets, and outbound fetches to its proxy/registry services.
+    const apiReferenceCsp = "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; img-src 'self' data: blob:; connect-src 'self' ws: wss: https://proxy.scalar.com https://api.scalar.com; font-src 'self' data: https://cdn.jsdelivr.net https://fonts.scalar.com; frame-ancestors 'none'";
+    fastify.addHook("onSend", (request, reply, _payload, done) => {
+        reply.header("X-Content-Type-Options", "nosniff");
+        reply.header("X-Frame-Options", "DENY");
+        const isApiReference = request.url.includes("/api-reference");
+        reply.header("Content-Security-Policy", isApiReference ? apiReferenceCsp : strictCsp);
+        if (options.enforceHsts) {
+            reply.header("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+        }
+        done();
+    });
+}

package/dist/sleep.js

@@ -0,0 +1,4 @@
+/** Async sleep utility. Usage: `await sleep(1000)` */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/urlSafeKey.js

@@ -0,0 +1,17 @@
+/** Characters allowed in URL path segments used as database keys (usernames, hostnames). */
+export const URL_SAFE_KEY_REGEX = /^[a-zA-Z0-9_-]+$/;
+export const URL_SAFE_KEY_MESSAGE = "Must contain only letters, numbers, hyphens, and underscores";
+/** Sanitize a string into a URL-safe key (replace spaces/special chars with hyphens). */
+export function toUrlSafeKey(input) {
+    return input
+        .trim()
+        .replace(/[^a-zA-Z0-9_-]/g, "-")
+        .replace(/-{2,}/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/** Throws if the value is not a valid URL-safe key. */
+export function assertUrlSafeKey(value, label) {
+    if (!URL_SAFE_KEY_REGEX.test(value)) {
+        throw new Error(`${label} "${value}" is not URL-safe. ${URL_SAFE_KEY_MESSAGE}`);
+    }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@naisys/common",
+  "version": "3.0.0-beta.10",
+  "type": "module",
+  "description": "[internal] Common utilities and constants for NAISYS",
+  "files": [
+    "dist",
+    "assets",
+    "!dist/**/*.map",
+    "!dist/**/*.d.ts",
+    "!dist/**/*.d.ts.map"
+  ],
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsc",
+    "npm:publish:dryrun": "npm publish --dry-run",
+    "npm:publish": "npm publish --access public"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./assets/*": "./assets/*"
+  }
+}