@happyvertical/smrt-agents 0.30.0

package/dist/server/serialization.d.ts

@@ -0,0 +1,58 @@
+import { ResolvedAgentAvailability } from '../tenant-agent.js';
+import { AgentAdminRoute, AgentUISlots } from '../ui.js';
+/**
+ * Serialized agent data for passing to client components.
+ *
+ * Includes manifest-derived fields (icon, permissions, slots)
+ * alongside resolution metadata (source, sourceTenantId).
+ */
+export interface SerializedAgent {
+    /** Agent instance ID, or a synthetic key if no instance exists */
+    id: string;
+    /** Human-readable name from manifest */
+    name?: string;
+    /** Human-readable agent class name (e.g., 'Praeco') */
+    agentClass: string;
+    /** Canonical agent type (qualified name when available) */
+    agentType: string;
+    /** STI type discriminator (same as agentType) */
+    _meta_type?: string;
+    /** UI slot definitions from manifest */
+    slots?: AgentUISlots;
+    /** Admin route declarations from manifest */
+    adminRoutes?: AgentAdminRoute[];
+    /** How this agent was resolved for the tenant */
+    source?: 'explicit' | 'inherited';
+    /** Which tenant the binding came from */
+    sourceTenantId?: string;
+    /** Merged permissions from manifest + tenant overrides */
+    permissions?: Record<string, boolean>;
+    /** Agent icon from manifest */
+    icon?: string;
+    /**
+     * Tenant-level config overrides, **secret-sanitized** for client transport.
+     *
+     * SECURITY (#1553, follow-up to #1552): the raw `TenantAgent.config` is the
+     * tenant's own override blob and is `@field({ sensitive: true })` (stripped
+     * from the generated CRUD api/mcp surfaces). This hand-written admin
+     * serialization runs it through `sanitizeConfig()` from
+     * `@happyvertical/smrt-config` before it leaves the server, so secret-shaped
+     * keys (apiKey/token/password/…) are dropped and secret-shaped values
+     * (`sk-…`, `AKIA…`, `Bearer …`, URL credentials, PEM blocks) are masked —
+     * non-secret config still reaches the authorized admin UI for display.
+     *
+     * This is **display-only**: do not edit-round-trip it back to the server
+     * (a masked value would overwrite the real secret). Best practice remains to
+     * reference secrets by id via `@happyvertical/smrt-secrets` so only an opaque
+     * handle is ever stored in tenant config.
+     */
+    config?: Record<string, any>;
+}
+/**
+ * Convert a ResolvedAgentAvailability to a serializable shape for the UI.
+ *
+ * @param resolved - Output from TenantAgentCollection.resolveForTenant()
+ * @returns Serialized agent data safe for JSON transport
+ */
+export declare function serializeResolvedAgent(resolved: ResolvedAgentAvailability): SerializedAgent;
+//# sourceMappingURL=serialization.d.ts.map

package/dist/server/serialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../src/server/serialization.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,iDAAiD;IACjD,MAAM,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC;IAClC,yCAAyC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,yBAAyB,GAClC,eAAe,CAkBjB"}

package/dist/server.js

@@ -0,0 +1,105 @@
+import { A as AgentConfig } from "./chunks/config-BYbOxt24.js";
+import { a, e, l, b } from "./chunks/manifest-utils-DLXfTOq0.js";
+import { sanitizeConfig } from "@happyvertical/smrt-config";
+function buildRouteMap(manifests) {
+  const routes = /* @__PURE__ */ new Map();
+  for (const manifest of manifests) {
+    const packageName = manifest.packageName;
+    for (const obj of Object.values(manifest.objects)) {
+      const config = obj.decoratorConfig;
+      if (!config) continue;
+      const api = config.api;
+      if (!api?.include || api.include.length === 0) continue;
+      const tableName = config.tableName;
+      const path = api.path || (tableName ? tableName.replace(/_/g, "-") : null);
+      if (!path) continue;
+      routes.set(path, {
+        className: obj.className,
+        allowedActions: api.include,
+        packageName
+      });
+    }
+  }
+  return routes;
+}
+function resolveAPIRoute(urlPath, routes) {
+  const normalized = urlPath.replace(/^\/+|\/+$/g, "");
+  if (!normalized) return null;
+  const segments = normalized.split("/");
+  if (segments.length === 1) {
+    const route = routes.get(segments[0]);
+    if (route) return { route };
+    return null;
+  }
+  if (segments.length === 2) {
+    const route = routes.get(segments[0]);
+    if (route) return { route, id: segments[1] };
+    return null;
+  }
+  if (segments.length === 3) {
+    const route = routes.get(segments[0]);
+    if (route) return { route, id: segments[1], action: segments[2] };
+    return null;
+  }
+  return null;
+}
+async function loadSlotConfigs(agents, dbOptions) {
+  if (agents.length === 0) {
+    return {};
+  }
+  try {
+    const configsByAgent = await AgentConfig.forAgents(
+      agents.map((agent) => agent.id),
+      dbOptions
+    );
+    const configs = {};
+    for (const [agentId, slotConfigs] of configsByAgent) {
+      const agentConfig = {};
+      for (const [slotId, configData] of slotConfigs) {
+        agentConfig[slotId] = configData;
+      }
+      if (Object.keys(agentConfig).length > 0) {
+        configs[agentId] = agentConfig;
+      }
+    }
+    return configs;
+  } catch (error) {
+    if (isMissingAgentConfigTableError(error)) {
+      return {};
+    }
+    throw error;
+  }
+}
+function isMissingAgentConfigTableError(error) {
+  const message = String(error?.message || error || "");
+  return message.includes("Run 'smrt db:migrate'") || /no such table[:\s]+agent_configs/i.test(message) || /relation .*agent_configs.*does not exist/i.test(message) || /table .*agent_configs.*doesn'?t exist/i.test(message);
+}
+function serializeResolvedAgent(resolved) {
+  const manifest = resolved.manifest;
+  return {
+    id: resolved.agentId || `${resolved.sourceTenantId}:${resolved.agentType}`,
+    name: manifest?.name || resolved.agentClass,
+    agentClass: resolved.agentClass,
+    agentType: resolved.agentType,
+    _meta_type: resolved.agentType,
+    slots: manifest?.uiSlots,
+    adminRoutes: manifest?.adminRoutes,
+    source: resolved.source,
+    sourceTenantId: resolved.sourceTenantId,
+    permissions: resolved.permissions,
+    icon: manifest?.icon,
+    // Secret-sanitize before the blob crosses into the client payload (#1553).
+    config: sanitizeConfig(resolved.config)
+  };
+}
+export {
+  buildRouteMap,
+  a as extractAgentManifest,
+  e as extractAgentPackagesFromConfig,
+  l as loadManifestsFromConfig,
+  b as loadManifestsFromPackages,
+  loadSlotConfigs,
+  resolveAPIRoute,
+  serializeResolvedAgent
+};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sources":["../src/server/api-routes.ts","../src/server/config-loader.ts","../src/server/serialization.ts"],"sourcesContent":["/**\n * Server-side API route resolution for SMRT agents\n *\n * Reads agent package manifests and builds a route map from resource\n * paths (e.g., 'performers', 'video-contents') to SmrtObject class\n * names and allowed CRUD actions. The catch-all API handler uses this\n * to resolve incoming requests.\n *\n * @module @happyvertical/smrt-agents/server\n */\n\nimport type { PackageManifest } from './manifest-utils.js';\n\n/**\n * Info about a single API route (one SmrtObject with api.include)\n */\nexport interface AgentAPIRouteInfo {\n  /** SmrtObject class name (e.g., 'Performer') */\n  className: string;\n  /** Allowed CRUD actions (e.g., ['list', 'get', 'create', 'update', 'delete']) */\n  allowedActions: string[];\n  /** Package that owns this resource */\n  packageName?: string;\n}\n\n/**\n * Result of resolving a URL path against the route map\n */\nexport interface ResolvedAPIRoute {\n  /** The matched route info */\n  route: AgentAPIRouteInfo;\n  /** Resource ID if path includes one (e.g., 'performers/abc-123') */\n  id?: string;\n  /** Custom action name if path includes one (e.g., 'performers/abc-123/generate-image') */\n  action?: string;\n}\n\n/**\n * Build a route map from loaded package manifests.\n *\n * Iterates all objects in each manifest, and for any object with a\n * `decoratorConfig.api.include` array, registers a route. The route\n * path is derived from `decoratorConfig.api.path` if set, otherwise\n * from the table name with underscores converted to hyphens.\n *\n * @param manifests - Array of parsed package manifest JSON objects\n * @returns Map of resource path -> route info\n *\n * @example\n * ```typescript\n * const manifests = [histrioManifest, praecoManifest];\n * const routes = buildRouteMap(manifests);\n * // routes.get('performers') => { className: 'Performer', allowedActions: ['list', 'get', 'create', 'update', 'delete'] }\n * // routes.get('video-contents') => { className: 'VideoShot', allowedActions: ['list', 'get', 'create', 'update'] }\n * ```\n */\nexport function buildRouteMap(\n  manifests: PackageManifest[],\n): Map<string, AgentAPIRouteInfo> {\n  const routes = new Map<string, AgentAPIRouteInfo>();\n\n  for (const manifest of manifests) {\n    const packageName = (manifest as Record<string, unknown>).packageName as\n      | string\n      | undefined;\n\n    for (const obj of Object.values(manifest.objects)) {\n      const config = obj.decoratorConfig as Record<string, unknown> | undefined;\n      if (!config) continue;\n\n      const api = config.api as\n        | { include?: string[]; path?: string }\n        | undefined;\n      if (!api?.include || api.include.length === 0) continue;\n\n      // Derive the URL path: explicit api.path, or table name with _ -> -\n      const tableName = config.tableName as string | undefined;\n      const path =\n        api.path || (tableName ? tableName.replace(/_/g, '-') : null);\n      if (!path) continue;\n\n      routes.set(path, {\n        className: obj.className,\n        allowedActions: api.include,\n        packageName,\n      });\n    }\n  }\n\n  return routes;\n}\n\n/**\n * Resolve a URL resource path against a route map.\n *\n * Handles three URL patterns:\n * - `performers` → list/create (no id)\n * - `performers/abc-123` → get/update/delete (with id)\n * - `performers/abc-123/generate-image` → custom action\n *\n * @param urlPath - The resource portion of the URL (after `/api/agents/{agentId}/`)\n * @param routes - Route map from {@link buildRouteMap}\n * @returns Resolved route with optional id/action, or null if no match\n */\nexport function resolveAPIRoute(\n  urlPath: string,\n  routes: Map<string, AgentAPIRouteInfo>,\n): ResolvedAPIRoute | null {\n  // Normalize: strip leading/trailing slashes\n  const normalized = urlPath.replace(/^\\/+|\\/+$/g, '');\n  if (!normalized) return null;\n\n  const segments = normalized.split('/');\n\n  // Try 1-segment: \"performers\"\n  if (segments.length === 1) {\n    const route = routes.get(segments[0]);\n    if (route) return { route };\n    return null;\n  }\n\n  // Try 2-segment: \"performers/{id}\"\n  if (segments.length === 2) {\n    const route = routes.get(segments[0]);\n    if (route) return { route, id: segments[1] };\n    return null;\n  }\n\n  // Try 3-segment: \"performers/{id}/{action}\"\n  if (segments.length === 3) {\n    const route = routes.get(segments[0]);\n    if (route) return { route, id: segments[1], action: segments[2] };\n    return null;\n  }\n\n  return null;\n}\n","/**\n * Server-side agent config loading utilities\n *\n * Loads slot configurations from the agent_configs table for a set of agents.\n * Agent-specific table loading (e.g., praeco_sources) stays in the host app.\n *\n * @module @happyvertical/smrt-agents/server\n */\n\nimport type { SmrtClassOptions } from '@happyvertical/smrt-core';\nimport { AgentConfig } from '../config.js';\n\n/**\n * Load slot configs for multiple agents from the agent_configs table.\n *\n * Returns a nested map: agentId -> slotId -> configData.\n * Agent-specific tables (e.g., praeco_sources, praeco_reports)\n * are NOT loaded here — those stay in the host application.\n *\n * @param agents - Array of agent identifiers (id + agentClass)\n * @param dbOptions - Database options for SmrtCollection.create()\n * @returns Map of agentId -> slotId -> config data\n */\nexport async function loadSlotConfigs(\n  agents: Array<{ id: string; agentClass: string }>,\n  dbOptions: SmrtClassOptions,\n): Promise<Record<string, Record<string, unknown>>> {\n  if (agents.length === 0) {\n    return {};\n  }\n\n  try {\n    const configsByAgent = await AgentConfig.forAgents(\n      agents.map((agent) => agent.id),\n      dbOptions,\n    );\n\n    const configs: Record<string, Record<string, unknown>> = {};\n    for (const [agentId, slotConfigs] of configsByAgent) {\n      const agentConfig: Record<string, unknown> = {};\n      for (const [slotId, configData] of slotConfigs) {\n        agentConfig[slotId] = configData;\n      }\n      if (Object.keys(agentConfig).length > 0) {\n        configs[agentId] = agentConfig;\n      }\n    }\n\n    return configs;\n  } catch (error) {\n    if (isMissingAgentConfigTableError(error)) {\n      return {};\n    }\n    throw error;\n  }\n}\n\nfunction isMissingAgentConfigTableError(error: unknown): boolean {\n  const message = String((error as Error)?.message || error || '');\n\n  return (\n    message.includes(\"Run 'smrt db:migrate'\") ||\n    /no such table[:\\s]+agent_configs/i.test(message) ||\n    /relation .*agent_configs.*does not exist/i.test(message) ||\n    /table .*agent_configs.*doesn'?t exist/i.test(message)\n  );\n}\n","/**\n * Serialization utilities for resolved agents\n *\n * Converts ResolvedAgentAvailability (database + manifest data) into\n * a JSON-safe shape suitable for passing to client components.\n *\n * @module @happyvertical/smrt-agents/server\n */\n\nimport { sanitizeConfig } from '@happyvertical/smrt-config';\nimport type { ResolvedAgentAvailability } from '../tenant-agent.js';\nimport type { AgentAdminRoute, AgentUISlots } from '../ui.js';\n\n/**\n * Serialized agent data for passing to client components.\n *\n * Includes manifest-derived fields (icon, permissions, slots)\n * alongside resolution metadata (source, sourceTenantId).\n */\nexport interface SerializedAgent {\n  /** Agent instance ID, or a synthetic key if no instance exists */\n  id: string;\n  /** Human-readable name from manifest */\n  name?: string;\n  /** Human-readable agent class name (e.g., 'Praeco') */\n  agentClass: string;\n  /** Canonical agent type (qualified name when available) */\n  agentType: string;\n  /** STI type discriminator (same as agentType) */\n  _meta_type?: string;\n  /** UI slot definitions from manifest */\n  slots?: AgentUISlots;\n  /** Admin route declarations from manifest */\n  adminRoutes?: AgentAdminRoute[];\n  /** How this agent was resolved for the tenant */\n  source?: 'explicit' | 'inherited';\n  /** Which tenant the binding came from */\n  sourceTenantId?: string;\n  /** Merged permissions from manifest + tenant overrides */\n  permissions?: Record<string, boolean>;\n  /** Agent icon from manifest */\n  icon?: string;\n  /**\n   * Tenant-level config overrides, **secret-sanitized** for client transport.\n   *\n   * SECURITY (#1553, follow-up to #1552): the raw `TenantAgent.config` is the\n   * tenant's own override blob and is `@field({ sensitive: true })` (stripped\n   * from the generated CRUD api/mcp surfaces). This hand-written admin\n   * serialization runs it through `sanitizeConfig()` from\n   * `@happyvertical/smrt-config` before it leaves the server, so secret-shaped\n   * keys (apiKey/token/password/…) are dropped and secret-shaped values\n   * (`sk-…`, `AKIA…`, `Bearer …`, URL credentials, PEM blocks) are masked —\n   * non-secret config still reaches the authorized admin UI for display.\n   *\n   * This is **display-only**: do not edit-round-trip it back to the server\n   * (a masked value would overwrite the real secret). Best practice remains to\n   * reference secrets by id via `@happyvertical/smrt-secrets` so only an opaque\n   * handle is ever stored in tenant config.\n   */\n  config?: Record<string, any>;\n}\n\n/**\n * Convert a ResolvedAgentAvailability to a serializable shape for the UI.\n *\n * @param resolved - Output from TenantAgentCollection.resolveForTenant()\n * @returns Serialized agent data safe for JSON transport\n */\nexport function serializeResolvedAgent(\n  resolved: ResolvedAgentAvailability,\n): SerializedAgent {\n  const manifest = resolved.manifest;\n\n  return {\n    id: resolved.agentId || `${resolved.sourceTenantId}:${resolved.agentType}`,\n    name: manifest?.name || resolved.agentClass,\n    agentClass: resolved.agentClass,\n    agentType: resolved.agentType,\n    _meta_type: resolved.agentType,\n    slots: manifest?.uiSlots as AgentUISlots | undefined,\n    adminRoutes: manifest?.adminRoutes as AgentAdminRoute[] | undefined,\n    source: resolved.source,\n    sourceTenantId: resolved.sourceTenantId,\n    permissions: resolved.permissions,\n    icon: manifest?.icon,\n    // Secret-sanitize before the blob crosses into the client payload (#1553).\n    config: sanitizeConfig(resolved.config) as SerializedAgent['config'],\n  };\n}\n"],"names":[],"mappings":"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"}