@easynet/agent-runtime 1.0.3 → 1.0.4

package/agent-runtime/src/cli/types.ts

@@ -0,0 +1,33 @@
+import type { AgentEventListener } from "@easynet/agent-common";
+import type { BotContext } from "../core/context.js";
+
+export const REACT = "react" as const;
+export const DEEP = "deep" as const;
+
+export type AgentKind = typeof REACT | typeof DEEP;
+
+export interface AppCliUiOptions {
+  userLabel?: string;
+  assistantLabel?: string;
+  useColor?: boolean;
+  renderMarkdown?: boolean;
+  echoUserQuestion?: boolean;
+  loadingText?: string | false;
+  loadingSpinner?: boolean;
+  readyText?: string | false;
+  interactiveIntro?: string | false;
+  processingSpinner?: boolean;
+  processingText?: string | false;
+}
+
+export interface AppCliOptions {
+  appName: string;
+  createBotContext: () => Promise<BotContext>;
+  interactiveCommands?: Record<string, InteractiveCommandHandler>;
+  eventListener?: AgentEventListener | AgentEventListener[];
+  onReady?: (ctx: BotContext) => void | Promise<void>;
+  onShutdown?: (ctx: BotContext) => void;
+  ui?: AppCliUiOptions;
+}
+
+export type InteractiveCommandHandler = (ctx: BotContext) => void | Promise<void>;

package/agent-runtime/src/cli.ts

@@ -0,0 +1,134 @@
+/**
+ * Shared CLI runner for agent apps.
+ * Provides: arg parsing, single-shot mode, interactive REPL, event logging.
+ */
+import { createConsoleAgentEventListener } from "@easynet/agent-common";
+import { parseArgs } from "./cli/args.js";
+import { createStructuredRunEventListener } from "./cli/event-listener.js";
+import { interactive } from "./cli/interactive.js";
+import { readDefaultAgentKindFromConfig, runOne } from "./cli/runtime.js";
+import { startLoadingSpinner } from "./cli/spinner.js";
+import { renderForTerminal } from "./cli/terminal-render.js";
+import { REACT, type AgentKind, type AppCliOptions, type AppCliUiOptions } from "./cli/types.js";
+
+export type { AppCliOptions, AppCliUiOptions };
+export { createStructuredRunEventListener };
+
+function createExitHandler(
+  appName: string,
+  onShutdown: AppCliOptions["onShutdown"],
+  ctx: Awaited<ReturnType<AppCliOptions["createBotContext"]>>,
+): (code: number) => never {
+  let didCleanup = false;
+
+  const cleanup = () => {
+    if (didCleanup) return;
+    didCleanup = true;
+    try {
+      onShutdown?.(ctx);
+    } catch (err) {
+      console.error(`${appName}: onShutdown hook failed:`, err instanceof Error ? err.message : err);
+    }
+  };
+
+  process.once("exit", cleanup);
+  const exitApp = (code: number): never => {
+    cleanup();
+    process.exit(code);
+  };
+  process.once("SIGINT", () => exitApp(130));
+  process.once("SIGTERM", () => exitApp(143));
+  return exitApp;
+}
+
+function subscribeEventListeners(options: AppCliOptions, ctx: Awaited<ReturnType<AppCliOptions["createBotContext"]>>): void {
+  if (process.env.AGENT_EVENT_STDERR === "1") {
+    ctx.events.subscribe(createConsoleAgentEventListener());
+  }
+
+  const listeners = Array.isArray(options.eventListener)
+    ? options.eventListener
+    : options.eventListener
+      ? [options.eventListener]
+      : [];
+  for (const listener of listeners) {
+    ctx.events.subscribe(listener);
+  }
+}
+
+async function runOnReady(options: AppCliOptions, appName: string, ctx: Awaited<ReturnType<AppCliOptions["createBotContext"]>>): Promise<void> {
+  if (!options.onReady) return;
+  try {
+    await options.onReady(ctx);
+  } catch (err) {
+    console.error(`${appName}: onReady hook failed:`, err instanceof Error ? err.message : err);
+  }
+}
+
+async function createContextWithLoading(options: AppCliOptions): Promise<Awaited<ReturnType<AppCliOptions["createBotContext"]>>> {
+  const loadingText = options.ui?.loadingText ?? `${options.appName}: loading config, LLM, memory, tools...`;
+  const useLoadingSpinner = options.ui?.loadingSpinner ?? false;
+  let stopLoadingSpinner: (() => void) | null = null;
+
+  if (loadingText !== false) {
+    if (useLoadingSpinner && Boolean(process.stderr.isTTY)) {
+      stopLoadingSpinner = startLoadingSpinner(loadingText);
+    } else {
+      console.error(loadingText);
+    }
+  }
+
+  const ctx = await options.createBotContext();
+  stopLoadingSpinner?.();
+  return ctx;
+}
+
+function printReady(options: AppCliOptions, kind: AgentKind): void {
+  const agentLabel = kind === REACT ? "ReAct (LangChain)" : "Deep (DeepAgents)";
+  const readyText = options.ui?.readyText ?? `Ready. Agent: ${agentLabel}`;
+  if (readyText !== false) {
+    console.error(readyText);
+  }
+}
+
+function resolveAgentKind(parsed: ReturnType<typeof parseArgs>, ctx: Awaited<ReturnType<AppCliOptions["createBotContext"]>>): AgentKind {
+  if (parsed.explicitKind) return parsed.kind;
+  return readDefaultAgentKindFromConfig(ctx) ?? parsed.kind;
+}
+
+async function runSingleQuery(
+  options: AppCliOptions,
+  ctx: Awaited<ReturnType<AppCliOptions["createBotContext"]>>,
+  kind: AgentKind,
+  query: string,
+): Promise<void> {
+  const text = await runOne(ctx, kind, query);
+  const useColor = options.ui?.useColor ?? (Boolean(process.stdout.isTTY) && !process.env.NO_COLOR);
+  const renderMarkdown = options.ui?.renderMarkdown ?? true;
+  console.log(renderForTerminal(text, { renderMarkdown, useColor }));
+}
+
+export function runAppCli(options: AppCliOptions): void {
+  const main = async () => {
+    const parsed = parseArgs();
+    const ctx = await createContextWithLoading(options);
+    const kind = resolveAgentKind(parsed, ctx);
+    const exitApp = createExitHandler(options.appName, options.onShutdown, ctx);
+
+    subscribeEventListeners(options, ctx);
+    await runOnReady(options, options.appName, ctx);
+    printReady(options, kind);
+
+    if (parsed.query) {
+      await runSingleQuery(options, ctx, kind, parsed.query);
+      exitApp(0);
+    }
+
+    await interactive(ctx, kind, options, exitApp);
+  };
+
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/agent-runtime/src/config/helpers.ts

@@ -0,0 +1,179 @@
+import { readdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { deepMerge, hydrateNamedScopedDefaults, loadModuleConfig } from "@easynet/agent-common";
+import { normalizeSkillConfig, resolveSkillRuntimeDefaults as resolveSkillRuntimeDefaultsFromModule } from "@easynet/agent-skill";
+import { normalizeAgentToolConfigRef } from "@easynet/agent-tool";
+import type { AgentProfileConfig, AgentMemoryProfileRef, AgentMemoryRuntimeRef } from "./types.js";
+
+const RUNTIME_CONFIG_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "../../config");
+
+let defaultProfilesPromise: Promise<Record<string, AgentProfileConfig>> | null = null;
+
+function asMemoryObject(input: unknown): Record<string, unknown> | undefined {
+  return typeof input === "object" && input !== null ? (input as Record<string, unknown>) : undefined;
+}
+
+function normalizeAgentMemoryRuntimeRef(raw: unknown): Partial<AgentMemoryRuntimeRef> {
+  const obj = asMemoryObject(raw);
+  if (!obj) return {};
+  const out: Partial<AgentMemoryRuntimeRef> = {};
+  if (obj.namespace_mode === "thread" || obj.namespace_mode === "fixed") out.namespace_mode = obj.namespace_mode;
+  if (typeof obj.namespace === "string") out.namespace = obj.namespace;
+  if (typeof obj.top_k === "number") out.top_k = obj.top_k;
+  if (typeof obj.budget_tokens === "number") out.budget_tokens = obj.budget_tokens;
+  if (typeof obj.auto_write === "boolean") out.auto_write = obj.auto_write;
+  if (obj.auto_write_scope === "thread" || obj.auto_write_scope === "cross_thread" || obj.auto_write_scope === "knowledge" || obj.auto_write_scope === "auto") out.auto_write_scope = obj.auto_write_scope;
+  if (typeof obj.auto_write_max_chars === "number") out.auto_write_max_chars = obj.auto_write_max_chars;
+  if (typeof obj.auto_write_user === "boolean") out.auto_write_user = obj.auto_write_user;
+  if (typeof obj.auto_write_assistant === "boolean") out.auto_write_assistant = obj.auto_write_assistant;
+  return out;
+}
+
+function normalizeAgentMemoryProfileRef(raw: unknown): Partial<AgentMemoryProfileRef> {
+  if (typeof raw === "string" && raw.trim().length > 0) return { ref: raw.trim() };
+  const obj = asMemoryObject(raw);
+  if (!obj) return {};
+  const runtime = normalizeAgentMemoryRuntimeRef(obj);
+  const out: Partial<AgentMemoryProfileRef> = { ...runtime };
+  if (typeof obj.ref === "string" && obj.ref.trim().length > 0) out.ref = obj.ref.trim();
+  return out;
+}
+
+async function resolveAgentMemoryRuntimeDefaultsFromModule(
+  memoryRef: string,
+  appRoot: string,
+): Promise<Partial<AgentMemoryRuntimeRef>> {
+  const common = await import("@easynet/agent-common");
+  const loadModuleConfigFn = (common as {
+    loadModuleConfig?: <TConfig>(options: { path: string; appRoot: string; unwrapSpec: boolean; fallback: TConfig }) => Promise<TConfig>;
+  }).loadModuleConfig;
+  const raw: Record<string, unknown> = typeof loadModuleConfigFn === "function"
+    ? await loadModuleConfigFn<Record<string, unknown>>({ path: memoryRef, appRoot, unwrapSpec: true, fallback: {} }) as Record<string, unknown>
+    : {};
+  const rootRuntime = normalizeAgentMemoryRuntimeRef(asMemoryObject(raw.runtime));
+  const memoryRuntime = normalizeAgentMemoryRuntimeRef(asMemoryObject(asMemoryObject(raw.memory)?.runtime));
+  return { ...rootRuntime, ...memoryRuntime };
+}
+
+function normalizeAgentModelConfigRef(raw: unknown): { ref?: string } {
+  if (typeof raw === "string" && raw.trim().length > 0) return { ref: raw.trim() };
+  if (typeof raw !== "object" || raw === null) return {};
+  const ref = (raw as { ref?: unknown }).ref;
+  if (typeof ref === "string" && ref.trim().length > 0) return { ref: ref.trim() };
+  return {};
+}
+
+async function discoverDefaultAgentProfileFiles(): Promise<Record<string, string>> {
+  try {
+    const entries = await readdir(RUNTIME_CONFIG_DIR, { withFileTypes: true });
+    return Object.fromEntries(
+      entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => {
+          const match = /^agent\.(.+)\.ya?ml$/i.exec(entry.name);
+          if (!match) return null;
+          return [match[1], resolve(RUNTIME_CONFIG_DIR, entry.name)] as const;
+        })
+        .filter((item): item is readonly [string, string] => item !== null),
+    );
+  } catch {
+    return {};
+  }
+}
+
+export function normalizeProfileConfig(
+  raw: Record<string, unknown> | undefined,
+  base?: AgentProfileConfig
+): AgentProfileConfig {
+  const merged: AgentProfileConfig = deepMerge({} as AgentProfileConfig, base ?? {});
+  if (!raw) return merged;
+
+  const models = normalizeAgentModelConfigRef(raw.models);
+  if (Object.keys(models).length > 0) merged.models = { ...(merged.models ?? {}), ...models };
+
+  const memory = normalizeAgentMemoryProfileRef(raw.memory);
+  if (Object.keys(memory).length > 0) merged.memory = { ...(merged.memory ?? {}), ...memory };
+
+  const tools = normalizeAgentToolConfigRef(raw.tools);
+  if (Object.keys(tools).length > 0) merged.tools = { ...(merged.tools ?? {}), ...tools };
+
+  const skills = normalizeSkillConfig(raw.skills);
+  if (Object.keys(skills).length > 0) merged.skills = { ...(merged.skills ?? {}), ...skills };
+
+  if (typeof raw.systemPrompt === "string") merged.systemPrompt = raw.systemPrompt;
+  if (typeof raw.maxSteps === "number") merged.maxSteps = raw.maxSteps;
+  if (typeof raw.printSteps === "boolean") merged.printSteps = raw.printSteps;
+  if (typeof raw.fallbackText === "string") merged.fallbackText = raw.fallbackText;
+  if (typeof raw.commandWindowLabel === "string") merged.commandWindowLabel = raw.commandWindowLabel;
+  if (typeof raw.recursionLimit === "number") merged.recursionLimit = raw.recursionLimit;
+  if (typeof raw.memoriesPath === "string") merged.memoriesPath = raw.memoriesPath;
+
+  return merged;
+}
+
+export async function hydrateAgentMemoryRuntimeDefaults(
+  agents: Record<string, AgentProfileConfig>,
+  appRoot: string
+): Promise<Record<string, AgentProfileConfig>> {
+  return hydrateNamedScopedDefaults<
+    AgentProfileConfig,
+    NonNullable<AgentProfileConfig["memory"]>,
+    Partial<NonNullable<AgentProfileConfig["memory"]>>
+  >(agents, {
+    appRoot,
+    getScope: (agent) => agent.memory as NonNullable<AgentProfileConfig["memory"]> | undefined,
+    setScope: (agent, memory) => ({ ...agent, memory }),
+    resolveDefaults: resolveAgentMemoryRuntimeDefaultsFromModule as (ref: string, appRoot: string) => Promise<Partial<NonNullable<AgentProfileConfig["memory"]>>>,
+  });
+}
+
+export async function hydrateAgentSkillsRuntimeDefaults(
+  agents: Record<string, AgentProfileConfig>,
+  appRoot: string
+): Promise<Record<string, AgentProfileConfig>> {
+  return hydrateNamedScopedDefaults<
+    AgentProfileConfig,
+    NonNullable<AgentProfileConfig["skills"]>,
+    Partial<NonNullable<AgentProfileConfig["skills"]>>
+  >(agents, {
+    appRoot,
+    getScope: (agent) => agent.skills as NonNullable<AgentProfileConfig["skills"]> | undefined,
+    setScope: (agent, skills) => ({ ...agent, skills }),
+    resolveDefaults: resolveSkillRuntimeDefaultsFromModule,
+  });
+}
+
+async function loadDefaultAgentProfiles(): Promise<Record<string, AgentProfileConfig>> {
+  if (defaultProfilesPromise) return defaultProfilesPromise;
+  defaultProfilesPromise = (async () => {
+    const defaultProfileFiles = await discoverDefaultAgentProfileFiles();
+    const entries = await Promise.all(
+      Object.entries(defaultProfileFiles).map(async ([name, filePath]) => {
+        try {
+          const raw = await loadModuleConfig<Record<string, unknown>>({
+            path: filePath,
+            unwrapSpec: true,
+            fallback: {},
+          });
+          return [name, normalizeProfileConfig(raw)] as const;
+        } catch {
+          return [name, {} as AgentProfileConfig] as const;
+        }
+      })
+    );
+    return Object.fromEntries(entries);
+  })();
+  return defaultProfilesPromise;
+}
+
+export async function applyDefaultAgentProfiles(
+  agents: Record<string, AgentProfileConfig>
+): Promise<Record<string, AgentProfileConfig>> {
+  const defaultsMap = await loadDefaultAgentProfiles();
+  const out: Record<string, AgentProfileConfig> = { ...agents };
+  for (const [name, defaults] of Object.entries(defaultsMap)) {
+    out[name] = deepMerge({} as AgentProfileConfig, defaults, out[name] ?? {});
+  }
+  return out;
+}

package/agent-runtime/src/config/index.ts

@@ -0,0 +1,245 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import { asObject, deepMerge, resolveConfigPath, resolveKindResourceFile } from "@easynet/agent-common";
+import { createSkillConfig, resolveSkillRuntimeDefaults } from "@easynet/agent-skill";
+import type {
+  ConfigApi,
+  AgentProfileConfig,
+  AgentRuntimeConfig,
+  AgentConfigDefaults,
+  SkillConfig,
+} from "./types.js";
+import {
+  applyDefaultAgentProfiles,
+  hydrateAgentMemoryRuntimeDefaults,
+  hydrateAgentSkillsRuntimeDefaults,
+  normalizeProfileConfig,
+} from "./helpers.js";
+
+export type { AgentProfileConfig, AgentRuntimeConfig, AgentConfigDefaults, SkillConfig } from "./types.js";
+
+export interface CreateRuntimeConfigOptions {
+  configPath?: string;
+  overrides?: Partial<AgentRuntimeConfig>;
+}
+
+const APP_ROOT = process.cwd();
+const RUNTIME_DIR = dirname(fileURLToPath(import.meta.url));
+const RUNTIME_PACKAGE_ROOT = resolvePath(RUNTIME_DIR, "../../");
+
+type ModuleDefaultConfigPaths = {
+  modelsPath?: string;
+  memoryPath?: string;
+  toolPath?: string;
+  skillPath?: string;
+};
+
+function resolveModuleConfigPath(pkgName: string, configRelativePath: string): string | undefined {
+  const candidates = [
+    resolvePath(RUNTIME_PACKAGE_ROOT, "node_modules", pkgName, configRelativePath),
+    resolvePath(APP_ROOT, "node_modules", pkgName, configRelativePath),
+  ];
+  return candidates.find((candidate) => existsSync(candidate));
+}
+
+const MODULE_DEFAULTS: ModuleDefaultConfigPaths = {
+  modelsPath: resolveModuleConfigPath("@easynet/agent-model", "config/model.yaml"),
+  memoryPath: resolveModuleConfigPath("@easynet/agent-memory", "config/memory.yaml"),
+  toolPath: resolveModuleConfigPath("@easynet/agent-tool", "config/tool.yaml"),
+  skillPath: resolveModuleConfigPath("@easynet/agent-skill", "config/skill.yaml"),
+};
+
+type SkillsDefaults = Pick<
+  NonNullable<AgentProfileConfig["skills"]>,
+  "mode" | "inject_metadata" | "embedding_threshold" | "keyword_threshold"
+>;
+
+type AppSpec = {
+  agents?: {
+    list?: Record<string, unknown>;
+  };
+};
+
+function toAgentConfigMap(config: AgentRuntimeConfig | undefined): Record<string, AgentProfileConfig> {
+  return config?.app?.agent ?? {};
+}
+
+function getFirstAgentName(config: AgentRuntimeConfig | undefined): string | undefined {
+  return Object.keys(toAgentConfigMap(config))[0];
+}
+
+function pickAgentConfig(
+  config: AgentRuntimeConfig | undefined,
+  agentName?: string
+): AgentProfileConfig | undefined {
+  const map = toAgentConfigMap(config);
+  if (agentName && map[agentName]) return map[agentName];
+  const firstName = getFirstAgentName(config);
+  return firstName ? map[firstName] : undefined;
+}
+
+function requirePath(pathValue: string | undefined, label: string): string {
+  if (!pathValue || pathValue.trim().length === 0) {
+    throw new Error(`Missing ${label} config path. Set it in agent profile or provide defaults.`);
+  }
+  return pathValue;
+}
+
+function toRuntimeApp(agents: Record<string, AgentProfileConfig>): AgentRuntimeConfig["app"] {
+  return {
+    agent: agents,
+  } as AgentRuntimeConfig["app"];
+}
+
+export async function loadAgentConfig(configPath?: string): Promise<AgentRuntimeConfig> {
+  const appResource = await resolveKindResourceFile<AppSpec>(configPath ?? "config/app.yaml", {
+    baseDir: APP_ROOT,
+    expectedApiVersion: "easynet.world/v1",
+    expectedKind: "AppConfig",
+  });
+  const spec = asObject(appResource.spec) as AppSpec | undefined;
+  const list = spec?.agents?.list ?? {};
+
+  const mergedAgents = Object.fromEntries(
+    Object.entries(list)
+      .map(([name, value]) => {
+        const entry = asObject(value);
+        if (!entry) return null;
+        const profileRaw = asObject((entry as { spec?: unknown }).spec) ?? entry;
+        const normalized = normalizeProfileConfig(profileRaw);
+        return [name, { ...normalized, profile: name } as AgentProfileConfig] as const;
+      })
+      .filter((item): item is readonly [string, AgentProfileConfig] => item !== null)
+  );
+
+  const withDefaults = await applyDefaultAgentProfiles(mergedAgents);
+  const memoryHydrated = await hydrateAgentMemoryRuntimeDefaults(withDefaults, APP_ROOT);
+  const skillsHydrated = await hydrateAgentSkillsRuntimeDefaults(memoryHydrated, APP_ROOT);
+
+  return {
+    app: toRuntimeApp(skillsHydrated),
+  };
+}
+
+export async function createRuntimeConfig(options: CreateRuntimeConfigOptions = {}): Promise<AgentRuntimeConfig> {
+  const base = await loadAgentConfig(options.configPath);
+  if (!options.overrides) return base;
+  return deepMerge({} as AgentRuntimeConfig, base, options.overrides);
+}
+
+export function getModelsConfigPath(
+  config?: AgentRuntimeConfig,
+  agentName?: string,
+  defaults?: AgentConfigDefaults
+): string {
+  const agent = pickAgentConfig(config, agentName);
+  const p = requirePath(agent?.models?.ref ?? defaults?.modelsPath ?? MODULE_DEFAULTS.modelsPath, "models");
+  return resolveConfigPath(p, APP_ROOT);
+}
+
+export function getMemoryConfigPath(
+  config?: AgentRuntimeConfig,
+  agentName?: string,
+  defaults?: AgentConfigDefaults
+): string {
+  const p = requirePath(
+    pickAgentConfig(config, agentName)?.memory?.ref ?? defaults?.memoryPath ?? MODULE_DEFAULTS.memoryPath,
+    "memory",
+  );
+  return resolveConfigPath(p, APP_ROOT);
+}
+
+export function getToolConfigPath(
+  config: AgentRuntimeConfig | undefined,
+  agentName: string | undefined,
+  defaults?: AgentConfigDefaults
+): string {
+  const name = agentName ?? getFirstAgentName(config);
+  const envFromProcess = (process.env.APP_ENV ?? process.env.NODE_ENV ?? "").trim().toLowerCase();
+  const env = envFromProcess || "development";
+  const isProd = env === "production" || env === "prod";
+  const tools = pickAgentConfig(config, name)?.tools;
+
+  const p = isProd
+    ? requirePath(
+        tools?.production ?? tools?.ref ?? defaults?.toolProdPath ?? defaults?.toolPath ?? MODULE_DEFAULTS.toolPath,
+        "tool(production)",
+      )
+    : requirePath(
+        tools?.development ?? tools?.ref ?? defaults?.toolDevPath ?? defaults?.toolPath ?? MODULE_DEFAULTS.toolPath,
+        "tool(development)",
+      );
+  return resolveConfigPath(p, APP_ROOT);
+}
+
+export function resolveDefaultAgentName(
+  config: AgentRuntimeConfig | undefined,
+  preferred?: string
+): string {
+  const agents = toAgentConfigMap(config);
+  const names = Object.keys(agents);
+  if (preferred && agents[preferred]) return preferred;
+  const configured = (config?.app as { defaultAgent?: unknown } | undefined)?.defaultAgent;
+  if (typeof configured === "string" && agents[configured]) return configured;
+  return names[0] ?? preferred ?? "";
+}
+
+export function createConfigApi(defaults?: AgentConfigDefaults): ConfigApi<AgentRuntimeConfig> {
+  return {
+    loadAgentConfig,
+    getModelsConfigPath: (config, agentName) => getModelsConfigPath(config, agentName, defaults),
+    getMemoryConfigPath: (config, agentName) => getMemoryConfigPath(config, agentName, defaults),
+    getToolConfigPath: (config, agentName) => getToolConfigPath(config, agentName, defaults),
+  };
+}
+
+export async function getSkillsConfig(
+  config: AgentRuntimeConfig | undefined,
+  agentName?: string,
+): Promise<SkillConfig | undefined> {
+  const raw = pickAgentConfig(config, agentName)?.skills;
+  const defaultSkillRef = MODULE_DEFAULTS.skillPath;
+  const appLocalSkillsDir = resolvePath(APP_ROOT, "skills");
+  const defaultsFromYaml = defaultSkillRef
+    ? await createSkillConfig({ configPath: resolveConfigPath(defaultSkillRef, APP_ROOT) })
+    : null;
+  const defaults: Partial<SkillsDefaults> = defaultsFromYaml
+    ? defaultsFromYaml
+    : (defaultSkillRef ? await resolveSkillRuntimeDefaults(defaultSkillRef, APP_ROOT).catch(() => ({})) : {});
+
+  if (!raw?.ref && existsSync(appLocalSkillsDir)) {
+    return {
+      path: appLocalSkillsDir,
+      mode: raw?.mode ?? defaults.mode,
+      inject_metadata: raw?.inject_metadata ?? defaults.inject_metadata,
+      embedding_threshold: raw?.embedding_threshold ?? defaults.embedding_threshold,
+      keyword_threshold: raw?.keyword_threshold ?? defaults.keyword_threshold,
+    };
+  }
+
+  const skillRef = raw?.ref ?? defaultSkillRef;
+  if (!skillRef) return undefined;
+
+  const resolvedRef = resolveConfigPath(skillRef, APP_ROOT);
+  const fromConfig = /\.ya?ml$/i.test(resolvedRef)
+    ? await createSkillConfig({
+        configPath: resolvedRef,
+        overrides: {
+          mode: raw?.mode,
+          inject_metadata: raw?.inject_metadata,
+          embedding_threshold: raw?.embedding_threshold,
+          keyword_threshold: raw?.keyword_threshold,
+        },
+      })
+    : null;
+  if (fromConfig) return fromConfig;
+
+  return {
+    path: resolvedRef,
+    mode: raw?.mode ?? defaults.mode,
+    inject_metadata: raw?.inject_metadata ?? defaults.inject_metadata,
+    embedding_threshold: raw?.embedding_threshold ?? defaults.embedding_threshold,
+    keyword_threshold: raw?.keyword_threshold ?? defaults.keyword_threshold,
+  };
+}

package/agent-runtime/src/config/types.ts

@@ -0,0 +1,62 @@
+import type { AgentToolConfigRef } from "@easynet/agent-tool";
+import type { SkillConfig, SkillConfigRef } from "@easynet/agent-skill";
+
+export type { SkillConfig, SkillConfigRef } from "@easynet/agent-skill";
+export type { AgentToolConfigRef } from "@easynet/agent-tool";
+
+export interface AgentMemoryRuntimeRef {
+  namespace_mode?: "thread" | "fixed";
+  namespace?: string;
+  top_k?: number;
+  budget_tokens?: number;
+  auto_write?: boolean;
+  auto_write_scope?: "thread" | "cross_thread" | "knowledge" | "auto";
+  auto_write_max_chars?: number;
+  auto_write_user?: boolean;
+  auto_write_assistant?: boolean;
+}
+
+export type AgentMemoryProfileRef = { ref?: string } & AgentMemoryRuntimeRef;
+
+export interface AgentModelConfigRef {
+  ref?: string;
+}
+
+export type AgentProfileConfig = {
+  profile?: string;
+  models?: AgentModelConfigRef;
+  memory?: AgentMemoryProfileRef;
+  tools?: AgentToolConfigRef;
+  skills?: SkillConfigRef;
+  systemPrompt?: string;
+  maxSteps?: number;
+  printSteps?: boolean;
+  fallbackText?: string;
+  commandWindowLabel?: string;
+  recursionLimit?: number;
+  memoriesPath?: string;
+};
+
+export interface BaseAgentConfig {
+  app?: {
+    agent?: Record<string, AgentProfileConfig>;
+    [key: string]: unknown;
+  };
+}
+
+export interface ConfigApi<TConfig> {
+  loadAgentConfig: (configPath?: string) => Promise<TConfig>;
+  getModelsConfigPath: (config: TConfig, agentName?: string) => string;
+  getMemoryConfigPath: (config: TConfig, agentName?: string) => string;
+  getToolConfigPath: (config: TConfig, agentName?: string) => string;
+}
+
+export interface AgentRuntimeConfig extends BaseAgentConfig {}
+
+export interface AgentConfigDefaults {
+  modelsPath?: string;
+  memoryPath?: string;
+  toolPath?: string;
+  toolDevPath?: string;
+  toolProdPath?: string;
+}