@naisys/common 3.0.0-beta.4 → 3.0.0-beta.6

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@naisys/common",
-  "version": "3.0.0-beta.4",
+  "version": "3.0.0-beta.6",
   "type": "module",
   "description": "[internal] Common utilities and constants for NAISYS",
   "files": [
     "dist",
     "assets",
-    "!dist/**/*.map"
+    "!dist/**/*.map",
+    "!dist/**/*.d.ts",
+    "!dist/**/*.d.ts.map"
   ],
   "scripts": {
     "clean": "rimraf dist",

package/dist/agentConfigFile.d.ts

@@ -1,62 +0,0 @@
-import { z } from "zod";
-export declare const commandProtectionValues: readonly ["none", "manual", "semi-auto", "auto"];
-export declare const AgentConfigFileSchema: z.ZodObject<{
-    username: z.ZodString;
-    title: z.ZodString;
-    agentPrompt: z.ZodString;
-    spendLimitDollars: z.ZodOptional<z.ZodNumber>;
-    spendLimitHours: z.ZodOptional<z.ZodNumber>;
-    tokenMax: z.ZodNumber;
-    shellModel: z.ZodString;
-    imageModel: z.ZodOptional<z.ZodString>;
-    mailEnabled: z.ZodOptional<z.ZodBoolean>;
-    chatEnabled: z.ZodOptional<z.ZodBoolean>;
-    webEnabled: z.ZodOptional<z.ZodBoolean>;
-    completeSessionEnabled: z.ZodOptional<z.ZodBoolean>;
-    debugPauseSeconds: z.ZodOptional<z.ZodNumber>;
-    wakeOnMessage: z.ZodOptional<z.ZodBoolean>;
-    commandProtection: z.ZodOptional<z.ZodEnum<{
-        none: "none";
-        manual: "manual";
-        "semi-auto": "semi-auto";
-        auto: "auto";
-    }>>;
-    initialCommands: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    multipleCommandsEnabled: z.ZodOptional<z.ZodBoolean>;
-    workspacesEnabled: z.ZodOptional<z.ZodBoolean>;
-    controlDesktop: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip>;
-export type AgentConfigFile = z.infer<typeof AgentConfigFileSchema>;
-/**
- * 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 declare function buildDefaultAgentConfig(username: string): AgentConfigFile;
-export declare const adminAgentConfig: {
-    username: string;
-    title: string;
-    shellModel: string;
-    agentPrompt: string;
-    tokenMax: number;
-    mailEnabled: true;
-    chatEnabled: true;
-    wakeOnMessage: true;
-    webEnabled: true;
-    spendLimitDollars: number;
-};
-export interface UserEntry {
-    userId: number;
-    username: string;
-    enabled: boolean;
-    leadUserId?: number;
-    assignedHostIds?: number[];
-    apiKey?: string;
-    config: AgentConfigFile;
-}

package/dist/agentStatus.d.ts

@@ -1,9 +0,0 @@
-export type AgentStatus = "active" | "available" | "disabled" | "offline" | "suspended";
-export declare function determineAgentStatus(opts: {
-    isActive: boolean;
-    isEnabled: boolean;
-    isSuspended: boolean;
-    assignedHostIds: number[] | undefined;
-    isHostOnline: (hostId: number) => boolean;
-    hasNonRestrictedOnlineHost: boolean;
-}): AgentStatus;

package/dist/authCache.d.ts

@@ -1,23 +0,0 @@
-export interface AuthCacheOptions {
-    /** TTL in ms for valid (authenticated) entries. Default: 60_000 */
-    ttlMs?: number;
-    /** TTL in ms for negative (unauthenticated) entries. Default: 10_000 */
-    negativeTtlMs?: number;
-    /** Maximum number of cached entries. Default: 1_000 */
-    maxSize?: number;
-}
-export declare class AuthCache<TUser> {
-    private cache;
-    private ttlMs;
-    private negativeTtlMs;
-    private maxSize;
-    constructor(options?: AuthCacheOptions);
-    /** Returns the cached user, `null` for a negative hit, or `undefined` on cache miss. */
-    get(key: string): TUser | null | undefined;
-    /** Cache a lookup result. Pass `null` to cache a negative (invalid token) result. */
-    set(key: string, user: TUser | null): void;
-    /** Remove a specific key from the cache (e.g. on logout). */
-    invalidate(key: string): void;
-    /** Clear the entire cache. */
-    clear(): void;
-}

package/dist/builtInModels.d.ts

@@ -1,3 +0,0 @@
-import { type ImageModel, type LlmModel } from "./modelTypes.js";
-export declare const builtInLlmModels: LlmModel[];
-export declare const builtInImageModels: ImageModel[];

package/dist/configUtils.d.ts

@@ -1 +0,0 @@
-export declare function sanitizeSpendLimit(num: any): number | undefined;

package/dist/constants.d.ts

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

package/dist/costUtils.d.ts

@@ -1,10 +0,0 @@
-/**
- * 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 declare function calculatePeriodBoundaries(hours: number): {
-    periodStart: Date;
-    periodEnd: Date;
-};

package/dist/errorHandler.d.ts

@@ -1,28 +0,0 @@
-/**
- * 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.
- */
-interface HandlerError {
-    statusCode?: number;
-    message: string;
-    name?: string;
-    code?: string;
-}
-interface HandlerRequest {
-    url: string;
-    method: string;
-    log: {
-        error: (obj: Record<string, unknown>, msg: string) => void;
-    };
-}
-interface HandlerReply {
-    status: (code: number) => HandlerReply;
-    header: (key: string, value: string) => HandlerReply;
-    send: (payload: string) => void;
-}
-export declare function commonErrorHandler(error: HandlerError, request: HandlerRequest, reply: HandlerReply): void;
-export {};

package/dist/formatFileSize.d.ts

@@ -1,4 +0,0 @@
-/** Maximum allowed file size for attachments (10 MB) */
-export declare const MAX_ATTACHMENT_SIZE: number;
-/** Format a byte count into a human-readable size string (e.g. "1.2 KB") */
-export declare function formatFileSize(bytes: number): string;

package/dist/globalConfigLoader.d.ts

@@ -1,25 +0,0 @@
-export interface ClientConfig {
-    shellCommand: {
-        outputTokenMax: number;
-        timeoutSeconds: number;
-        maxTimeoutSeconds: number;
-    };
-    retrySecondsMax: number;
-    webTokenMax: number;
-    compactSessionEnabled: boolean;
-    preemptiveCompactEnabled: boolean;
-    googleSearchEngineId?: string;
-    spendLimitDollars?: number;
-    spendLimitHours?: number;
-    variableMap: Record<string, string>;
-    shellVariableMap: Record<string, string>;
-    useToolsForLlmConsoleResponses: boolean;
-    autoStartAgentsOnMessage: boolean;
-}
-/**
- * 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 declare function buildClientConfig(variables: Record<string, string | undefined>, shellExportKeys?: Set<string>): ClientConfig;

package/dist/hateoas-types.d.ts

@@ -1,76 +0,0 @@
-import { z } from "zod/v4";
-export declare const HateoasLinkSchema: z.ZodObject<{
-    rel: z.ZodString;
-    href: z.ZodString;
-    method: z.ZodOptional<z.ZodString>;
-    title: z.ZodOptional<z.ZodString>;
-    schema: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type HateoasLink = z.infer<typeof HateoasLinkSchema>;
-export declare const AlternateEncodingSchema: z.ZodObject<{
-    contentType: z.ZodString;
-    description: z.ZodOptional<z.ZodString>;
-    fileFields: z.ZodArray<z.ZodString>;
-}, z.core.$strip>;
-export type AlternateEncoding = z.infer<typeof AlternateEncodingSchema>;
-export declare const HateoasActionSchema: z.ZodObject<{
-    rel: z.ZodString;
-    href: z.ZodString;
-    method: z.ZodString;
-    title: z.ZodOptional<z.ZodString>;
-    schema: z.ZodOptional<z.ZodString>;
-    body: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    alternateEncoding: z.ZodOptional<z.ZodObject<{
-        contentType: z.ZodString;
-        description: z.ZodOptional<z.ZodString>;
-        fileFields: z.ZodArray<z.ZodString>;
-    }, z.core.$strip>>;
-    disabled: z.ZodOptional<z.ZodBoolean>;
-    disabledReason: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
-}, z.core.$strip>;
-export type HateoasAction = z.infer<typeof HateoasActionSchema>;
-export declare const HateoasActionTemplateSchema: z.ZodObject<{
-    rel: z.ZodString;
-    hrefTemplate: z.ZodString;
-    method: z.ZodString;
-    title: z.ZodOptional<z.ZodString>;
-    schema: z.ZodOptional<z.ZodString>;
-    body: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    alternateEncoding: z.ZodOptional<z.ZodObject<{
-        contentType: z.ZodString;
-        description: z.ZodOptional<z.ZodString>;
-        fileFields: z.ZodArray<z.ZodString>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-export type HateoasActionTemplate = z.infer<typeof HateoasActionTemplateSchema>;
-export declare const HateoasLinkTemplateSchema: z.ZodObject<{
-    rel: z.ZodString;
-    hrefTemplate: z.ZodString;
-    title: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type HateoasLinkTemplate = z.infer<typeof HateoasLinkTemplateSchema>;
-export declare const HateoasLinksSchema: z.ZodObject<{
-    _links: z.ZodArray<z.ZodObject<{
-        rel: z.ZodString;
-        href: z.ZodString;
-        method: z.ZodOptional<z.ZodString>;
-        title: z.ZodOptional<z.ZodString>;
-        schema: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-    _actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        rel: z.ZodString;
-        href: z.ZodString;
-        method: z.ZodString;
-        title: z.ZodOptional<z.ZodString>;
-        schema: z.ZodOptional<z.ZodString>;
-        body: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        alternateEncoding: z.ZodOptional<z.ZodObject<{
-            contentType: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
-            fileFields: z.ZodArray<z.ZodString>;
-        }, z.core.$strip>>;
-        disabled: z.ZodOptional<z.ZodBoolean>;
-        disabledReason: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
-    }, z.core.$strip>>>;
-}, z.core.$strip>;
-export type HateoasLinks = z.infer<typeof HateoasLinksSchema>;

package/dist/hateoas.d.ts

@@ -1,35 +0,0 @@
-import type { HateoasAction, HateoasActionTemplate, HateoasLinkTemplate } from "./hateoas-types.js";
-/**
- * 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 declare function hasAction(actions: HateoasAction[] | undefined, rel: string, opts?: {
-    includeDisabled: boolean;
-}): HateoasAction | undefined;
-export declare function hasActionTemplate(templates: HateoasActionTemplate[] | undefined, rel: string): HateoasActionTemplate | undefined;
-export declare function hasLinkTemplate(templates: HateoasLinkTemplate[] | undefined, rel: string): HateoasLinkTemplate | undefined;
-export interface ActionDef<T> {
-    rel: string;
-    path?: string;
-    href?: string;
-    method: string;
-    title: string;
-    schema?: string;
-    body?: Record<string, unknown>;
-    permission?: string;
-    statuses?: string[];
-    visibleWhen?: (ctx: T) => boolean;
-    hideWithoutPermission?: boolean;
-    disabledWhen?: (ctx: T) => string | string[] | null;
-}
-export declare function resolveActions<T>(defs: ActionDef<T>[], baseHref: string, ctx: T, checkPermission: (permission: string) => boolean): HateoasAction[];
-export declare function permGate(hasPerm: boolean, permission: string): {
-    disabled?: undefined;
-    disabledReason?: undefined;
-} | {
-    disabled: true;
-    disabledReason: string;
-};
-/** Normalize a `disabledReason` (string | string[] | undefined) to a single display string. */
-export declare function formatDisabledReason(reason: string | string[] | undefined): string | undefined;

package/dist/hostedServices.d.ts

@@ -1,14 +0,0 @@
-/**
- * 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.
- */
-/** Starts the Hub server. Exported by @naisys/hub */
-export type StartHub = (startupType: "standalone" | "hosted", startSupervisor?: boolean, plugins?: "erp"[], startupAgentPath?: string) => Promise<{
-    hubPort: number;
-    supervisorPort?: number;
-}>;
-/** Starts the Supervisor web server. Exported by @naisys/supervisor */
-export type StartServer = (startupType: "standalone" | "hosted", plugins?: "erp"[], hubPort?: number) => Promise<number>;

package/dist/index.d.ts

@@ -1,19 +0,0 @@
-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.d.ts

@@ -1,15 +0,0 @@
-/**
- * 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.
- */
-interface FastifyLike {
-    addContentTypeParser(contentType: string, opts: {
-        parseAs: "string";
-    }, parser: (req: unknown, body: string, done: (err: Error | null, body?: unknown) => void) => void): void;
-}
-export declare function registerLenientJsonParser(fastify: FastifyLike): void;
-export {};

package/dist/mimeTypes.d.ts

@@ -1 +0,0 @@
-export declare function mimeFromFilename(filename: string): string;

package/dist/modelTypes.d.ts

@@ -1,107 +0,0 @@
-import { z } from "zod";
-export declare enum LlmApiType {
-    OpenAI = "openai",
-    Google = "google",
-    Anthropic = "anthropic",
-    Mock = "mock",
-    None = "none"
-}
-export declare const LlmModelSchema: z.ZodObject<{
-    key: z.ZodString;
-    label: z.ZodString;
-    versionName: z.ZodString;
-    apiType: z.ZodEnum<typeof LlmApiType>;
-    maxTokens: z.ZodNumber;
-    baseUrl: z.ZodOptional<z.ZodString>;
-    apiKeyVar: z.ZodString;
-    inputCost: z.ZodDefault<z.ZodNumber>;
-    outputCost: z.ZodDefault<z.ZodNumber>;
-    cacheWriteCost: z.ZodOptional<z.ZodNumber>;
-    cacheReadCost: z.ZodOptional<z.ZodNumber>;
-    cacheTtlSeconds: z.ZodOptional<z.ZodNumber>;
-    supportsVision: z.ZodOptional<z.ZodBoolean>;
-    supportsHearing: z.ZodOptional<z.ZodBoolean>;
-    supportsComputerUse: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip>;
-export type LlmModel = z.infer<typeof LlmModelSchema>;
-export declare const ImageModelSchema: z.ZodObject<{
-    key: z.ZodString;
-    label: z.ZodString;
-    versionName: z.ZodString;
-    size: z.ZodString;
-    baseUrl: z.ZodOptional<z.ZodString>;
-    apiKeyVar: z.ZodString;
-    cost: z.ZodNumber;
-    quality: z.ZodOptional<z.ZodEnum<{
-        standard: "standard";
-        hd: "hd";
-        high: "high";
-        medium: "medium";
-        low: "low";
-    }>>;
-}, z.core.$strip>;
-export type ImageModel = z.infer<typeof ImageModelSchema>;
-export declare const CustomModelsFileSchema: z.ZodObject<{
-    llmModels: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        key: z.ZodString;
-        label: z.ZodString;
-        versionName: z.ZodString;
-        apiType: z.ZodEnum<typeof LlmApiType>;
-        maxTokens: z.ZodNumber;
-        baseUrl: z.ZodOptional<z.ZodString>;
-        apiKeyVar: z.ZodString;
-        inputCost: z.ZodDefault<z.ZodNumber>;
-        outputCost: z.ZodDefault<z.ZodNumber>;
-        cacheWriteCost: z.ZodOptional<z.ZodNumber>;
-        cacheReadCost: z.ZodOptional<z.ZodNumber>;
-        cacheTtlSeconds: z.ZodOptional<z.ZodNumber>;
-        supportsVision: z.ZodOptional<z.ZodBoolean>;
-        supportsHearing: z.ZodOptional<z.ZodBoolean>;
-        supportsComputerUse: z.ZodOptional<z.ZodBoolean>;
-    }, z.core.$strip>>>;
-    imageModels: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        key: z.ZodString;
-        label: z.ZodString;
-        versionName: z.ZodString;
-        size: z.ZodString;
-        baseUrl: z.ZodOptional<z.ZodString>;
-        apiKeyVar: z.ZodString;
-        cost: z.ZodNumber;
-        quality: z.ZodOptional<z.ZodEnum<{
-            standard: "standard";
-            hd: "hd";
-            high: "high";
-            medium: "medium";
-            low: "low";
-        }>>;
-    }, z.core.$strip>>>;
-}, z.core.$strip>;
-export type CustomModelsFile = z.infer<typeof CustomModelsFileSchema>;
-export type ModelDbType = "llm" | "image";
-/** Row shape returned from prisma models table */
-export interface ModelDbRow {
-    id: number;
-    key: string;
-    type: ModelDbType;
-    label: string;
-    version_name: string;
-    is_builtin: boolean;
-    is_custom: boolean;
-    meta: string;
-}
-/** Fields for prisma models.createMany / update (without id, created_at, updated_at) */
-export interface ModelDbFields {
-    key: string;
-    type: ModelDbType;
-    label: string;
-    version_name: string;
-    is_builtin: boolean;
-    is_custom: boolean;
-    meta: string;
-}
-export declare function llmModelToDbFields(model: LlmModel, isBuiltin: boolean, isCustom: boolean): ModelDbFields;
-export declare function imageModelToDbFields(model: ImageModel, isBuiltin: boolean, isCustom: boolean): ModelDbFields;
-export declare function dbFieldsToLlmModel(row: ModelDbRow): LlmModel;
-export declare function dbFieldsToImageModel(row: ModelDbRow): ImageModel;
-export declare function getAllLlmModels(customLlmModels?: LlmModel[]): LlmModel[];
-export declare function getAllImageModels(customImageModels?: ImageModel[]): ImageModel[];

package/dist/securityHeaders.d.ts

@@ -1,14 +0,0 @@
-/**
- * Shared security-header hook for Fastify servers.
- *
- * Interfaces are duck-typed so @naisys/common doesn't need a Fastify dependency.
- */
-interface HeaderReply {
-    header: (key: string, value: string) => HeaderReply;
-}
-export declare function registerSecurityHeaders(fastify: {
-    addHook: (name: string, fn: (request: unknown, reply: HeaderReply, payload: unknown, done: () => void) => void) => void;
-}, options: {
-    enforceHsts: boolean;
-}): void;
-export {};

package/dist/sleep.d.ts

@@ -1,2 +0,0 @@
-/** Async sleep utility. Usage: `await sleep(1000)` */
-export declare function sleep(ms: number): Promise<void>;

package/dist/urlSafeKey.d.ts

@@ -1,7 +0,0 @@
-/** Characters allowed in URL path segments used as database keys (usernames, hostnames). */
-export declare const URL_SAFE_KEY_REGEX: RegExp;
-export declare 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 declare function toUrlSafeKey(input: string): string;
-/** Throws if the value is not a valid URL-safe key. */
-export declare function assertUrlSafeKey(value: string, label: string): void;