@easynet/agent-runtime 1.0.3 → 1.0.4

package/agent-runtime/src/core/context.ts

@@ -0,0 +1,266 @@
+import { createAgentModelRegistry } from "@easynet/agent-model";
+import { createAgentMemory as createMemoryClient } from "@easynet/agent-memory/internal";
+import { createLangChainAgentTools } from "@easynet/agent-tool/api";
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import {
+  createAgentEventBus,
+  loadYamlFile,
+  asObject,
+  type AgentEventBus,
+} from "@easynet/agent-common";
+import type { SkillConfig } from "@easynet/agent-skill";
+import { createSkills, type EmbedFn, type SkillSet } from "@easynet/agent-skill";
+import { getSkillsConfig } from "../config/index.js";
+import type { BaseAgentConfig, ConfigApi } from "../config/types.js";
+import { resolve, dirname } from "node:path";
+export type { BaseAgentConfig } from "../config/types.js";
+export type { ConfigApi } from "../config/types.js";
+
+export type AgentName = string;
+
+export type BotTool = ReturnType<typeof createLangChainAgentTools>[number];
+
+/** Minimal memory interface used by the runtime. */
+export interface AgentMemory {
+  memorize(namespace: string, type: string, contentOrUrl: string | URL, metadata?: Record<string, unknown>): Promise<unknown>;
+  recall(req: { namespace: string; query?: string; types?: string[]; topK?: number; budgetTokens?: number }): Promise<{ items: unknown[]; injectedText: string; traceId: string }>;
+  deleteByNamespace(namespace: string): Promise<void>;
+  getByKey(namespace: string, key: string): Promise<unknown>;
+  deleteByKey(namespace: string, key: string): Promise<void>;
+}
+
+export interface BotContext<TConfig extends BaseAgentConfig = BaseAgentConfig, TTool = BotTool> {
+  llm: BaseChatModel;
+  memory: AgentMemory;
+  tools: TTool[];
+  config: TConfig;
+  events: AgentEventBus;
+  skillSet?: SkillSet;
+}
+
+export interface CreateContextOptions<TTool = BotTool> {
+  configPath?: string;
+  agentName?: AgentName;
+  events?: AgentEventBus;
+  llm?: BaseChatModel;
+  memory?: AgentMemory;
+  tools?: TTool[];
+}
+
+function publishEvent(
+  events: AgentEventBus,
+  name: string,
+  from: string,
+  to: string,
+  payload?: unknown
+): void {
+  events.publish({ name, from, to, payload });
+}
+
+function injectSkillsRuntimeConfig(
+  config: BaseAgentConfig,
+  agentName: string,
+  values: Pick<SkillConfig, "mode" | "inject_metadata" | "embedding_threshold" | "keyword_threshold">
+): void {
+  const agentConfig = config.app?.agent?.[agentName];
+  if (!agentConfig) return;
+  agentConfig.skills = {
+    ...(agentConfig.skills ?? {}),
+    ...values,
+  };
+}
+
+export function createContextBuilders<TConfig extends BaseAgentConfig>(params: {
+  configApi: ConfigApi<TConfig>;
+}) {
+  const {
+    loadAgentConfig,
+    getModelsConfigPath,
+    getMemoryConfigPath,
+    getToolConfigPath,
+  } = params.configApi;
+
+  const pickDefaultAgentName = (config: TConfig): AgentName | undefined => {
+    const names = Object.keys(config.app?.agent ?? {});
+    return names[0];
+  };
+
+  async function getAgentLlm(
+    config: TConfig,
+    events: AgentEventBus,
+    agentName?: AgentName
+  ): Promise<BaseChatModel> {
+    const modelsPath = getModelsConfigPath(config, agentName ?? pickDefaultAgentName(config));
+    publishEvent(events, "llm.init.start", "app", "llm", { configPath: modelsPath });
+    const modelRegistry = await createAgentModelRegistry(modelsPath);
+    const llm = await modelRegistry.getChatModel();
+    publishEvent(events, "llm.init.done", "llm", "app");
+    return llm;
+  }
+
+  async function getAgentMemory(
+    config: TConfig,
+    events: AgentEventBus,
+    agentName?: AgentName
+  ): Promise<AgentMemory> {
+    const memoryPath = getMemoryConfigPath(config, agentName ?? pickDefaultAgentName(config));
+    publishEvent(events, "memory.init.start", "app", "memory", { configPath: memoryPath });
+    const memory = await createMemoryClient({ configPath: memoryPath });
+    publishEvent(events, "memory.init.done", "memory", "app");
+    return memory;
+  }
+
+  async function getAgentTools(
+    config: TConfig,
+    events: AgentEventBus,
+    agentName?: AgentName
+  ): Promise<BotTool[]> {
+    const toolPath = getToolConfigPath(config, agentName ?? pickDefaultAgentName(config));
+    publishEvent(events, "tools.init.start", "app", "tools", { configPath: toolPath });
+    const tools = createLangChainAgentTools({ configFilePath: toolPath });
+    publishEvent(events, "tools.init.done", "tools", "app", { count: tools.length });
+    return tools;
+  }
+
+  async function createAgent(options: CreateContextOptions<BotTool> = {}): Promise<BotContext<TConfig, BotTool>> {
+    const config = await loadAgentConfig(options.configPath);
+    const agentName = options.agentName ?? pickDefaultAgentName(config);
+    const events = options.events ?? createAgentEventBus();
+    publishEvent(events, "agent.context.init.start", "app", "runtime");
+
+    const [llm, memory, tools] = await Promise.all([
+      options.llm ?? getAgentLlm(config, events, agentName),
+      options.memory ?? getAgentMemory(config, events, agentName),
+      options.tools ?? getAgentTools(config, events, agentName),
+    ]);
+
+    const appConfig = config as unknown as BaseAgentConfig;
+    const skillSet = await initializeSkills({
+      appConfig,
+      config,
+      agentName,
+      events,
+      getModelsConfigPath: (c, name) => getModelsConfigPath(c as TConfig, name),
+      pickDefaultAgentName: (c) => pickDefaultAgentName(c as TConfig),
+    });
+
+    publishEvent(events, "agent.context.init.done", "runtime", "app");
+    return { llm, memory, tools, config, events, skillSet };
+  }
+
+  async function createBotContext(
+    configPath?: string,
+    agentName?: AgentName
+  ): Promise<BotContext<TConfig, BotTool>> {
+    return createAgent({ configPath, agentName });
+  }
+
+  return {
+    getAgentLlm,
+    getAgentMemory,
+    getAgentTools,
+    // Backward-compatible aliases
+    createAgentLlm: getAgentLlm,
+    createAgentMemory: getAgentMemory,
+    createAgentTools: getAgentTools,
+    createAgent,
+    createBotContext,
+  };
+}
+
+async function initializeSkills(input: {
+  appConfig: BaseAgentConfig;
+  config: BaseAgentConfig;
+  agentName?: AgentName;
+  events: AgentEventBus;
+  getModelsConfigPath: (config: BaseAgentConfig, agentName?: AgentName) => string;
+  pickDefaultAgentName: (config: BaseAgentConfig) => AgentName | undefined;
+}): Promise<SkillSet | undefined> {
+  const skillsConfig = await getSkillsConfig(input.appConfig, input.agentName);
+  if (!skillsConfig) return undefined;
+  publishEvent(input.events, "skills.init.start", "app", "skills", { path: skillsConfig.path });
+  const embedFn = buildSkillsEmbedFn(input.config, input.agentName, input.getModelsConfigPath, input.pickDefaultAgentName);
+  const skillsDir = await resolveSkillsDir(skillsConfig.path);
+  const skillSet = await createSkills({ path: skillsDir, embed: embedFn });
+  const mode = applySkillsPromptAndMetadata(input.appConfig, input.agentName, skillsConfig, skillSet);
+  publishEvent(input.events, "skills.init.done", "skills", "app", { count: skillSet.list().length, mode });
+  return skillSet;
+}
+
+function buildSkillsEmbedFn(
+  config: BaseAgentConfig,
+  agentName: AgentName | undefined,
+  getModelsConfigPath: (config: BaseAgentConfig, agentName?: AgentName) => string,
+  pickDefaultAgentName: (config: BaseAgentConfig) => AgentName | undefined,
+): EmbedFn | undefined {
+  const modelsPath = getModelsConfigPath(config, agentName ?? pickDefaultAgentName(config));
+  const lazyEmbed: EmbedFn = async (input: string | string[]) => {
+    const modelRegistry = await createAgentModelRegistry(modelsPath);
+    const embeddings = modelRegistry.getEmbeddingModel();
+    if (Array.isArray(input)) return embeddings.embedDocuments(input);
+    const one = await embeddings.embedQuery(input);
+    return [one];
+  };
+  return lazyEmbed;
+}
+
+function applySkillsPromptAndMetadata(
+  appConfig: BaseAgentConfig,
+  agentName: AgentName | undefined,
+  skillsConfig: SkillConfig,
+  skillSet: SkillSet,
+): string {
+  const mode = skillsConfig.mode ?? "prompt";
+  if (agentName) {
+    injectSkillsRuntimeConfig(appConfig, agentName, {
+      mode: skillsConfig.mode,
+      inject_metadata: skillsConfig.inject_metadata,
+      embedding_threshold: skillsConfig.embedding_threshold,
+      keyword_threshold: skillsConfig.keyword_threshold,
+    });
+  }
+  if (mode === "prompt" && skillsConfig.inject_metadata !== false) {
+    injectSkillsPromptSection(appConfig, agentName, skillSet.promptSection());
+  }
+  return mode;
+}
+
+function injectSkillsPromptSection(
+  appConfig: BaseAgentConfig,
+  agentName: AgentName | undefined,
+  section: string | undefined,
+): void {
+  if (!section || !agentName) return;
+  const agentConfig = appConfig.app?.agent?.[agentName];
+  if (!agentConfig) return;
+  const currentPrompt = agentConfig.systemPrompt ?? "";
+  agentConfig.systemPrompt = currentPrompt.trimEnd() + "\n\n" + section;
+}
+
+export interface AppContextBuilders {
+  getAgentLlm: (config: BaseAgentConfig, events: AgentEventBus, agentName?: AgentName) => Promise<BaseChatModel>;
+  getAgentMemory: (config: BaseAgentConfig, events: AgentEventBus, agentName?: AgentName) => Promise<AgentMemory>;
+  getAgentTools: (config: BaseAgentConfig, events: AgentEventBus, agentName?: AgentName) => Promise<BotTool[]>;
+  createAgentLlm: (config: BaseAgentConfig, events: AgentEventBus, agentName?: AgentName) => Promise<BaseChatModel>;
+  createAgentMemory: (config: BaseAgentConfig, events: AgentEventBus, agentName?: AgentName) => Promise<AgentMemory>;
+  createAgentTools: (config: BaseAgentConfig, events: AgentEventBus, agentName?: AgentName) => Promise<BotTool[]>;
+  createAgent: (options?: CreateContextOptions<BotTool>) => Promise<BotContext>;
+  createBotContext: (configPath?: string, agentName?: AgentName) => Promise<BotContext>;
+}
+
+/**
+ * Resolve skills directory path from either a YAML config file or a direct path.
+ * If the path ends with .yaml/.yml, loads the YAML and extracts the `path:` field.
+ */
+async function resolveSkillsDir(skillsPath: string): Promise<string> {
+  if (/\.ya?ml$/i.test(skillsPath)) {
+    const raw = await loadYamlFile<{ path?: string }>(skillsPath);
+    const spec = asObject((raw as { spec?: unknown } | undefined)?.spec);
+    const pathRef = typeof spec?.path === "string" ? spec.path : raw?.path;
+    if (!pathRef) {
+      throw new Error(`skills config missing "path" field: ${skillsPath}`);
+    }
+    return resolve(dirname(skillsPath), pathRef);
+  }
+  return skillsPath;
+}

package/agent-runtime/src/index.ts

@@ -0,0 +1,55 @@
+export {
+  createContextBuilders,
+  type AppContextBuilders,
+  type BaseAgentConfig,
+  type BotContext,
+  type BotTool,
+  type CreateContextOptions,
+  type ConfigApi,
+} from "./core/context.js";
+
+export {
+  createReactAgent,
+  printReactSteps,
+  type ReactAgentOptions,
+  type ReactAgentRuntime,
+} from "./agents/react-agent.js";
+
+export {
+  createDeepAgent,
+  type DeepAgentOptions,
+  type DeepAgentRuntime,
+} from "./agents/deep-agent.js";
+
+export {
+  createConfigApi,
+  createRuntimeConfig,
+  loadAgentConfig,
+  getModelsConfigPath,
+  getMemoryConfigPath,
+  getToolConfigPath,
+  resolveDefaultAgentName,
+  type CreateRuntimeConfigOptions,
+  type AgentRuntimeConfig,
+  type AgentConfigDefaults,
+  type AgentProfileConfig,
+} from "./config/index.js";
+
+export {
+  runAppCli,
+  createStructuredRunEventListener,
+  type AppCliOptions,
+  type AppCliUiOptions,
+} from "./cli.js";
+
+export {
+  malformedToolCallMiddleware,
+  type MalformedToolCallMiddlewareConfig,
+} from "./middleware/malformed-tool-call-middleware.js";
+
+export {
+  createSubAgentRunner,
+  type SubAgentRunner,
+  type SubAgentOptions,
+  type SubAgentResult,
+} from "./agents/sub-agent.js";

package/agent-runtime/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/apps/imessagebot/README.md

@@ -0,0 +1,38 @@
+# iMessageBot
+
+iMessageBot is an application built on the **@easynet** agent framework. It runs two agents:
+
+1. **ReAct agent** - LangChain ReAct with tools and memory.
+2. **Deep agent** - DeepAgents with persistent memory store.
+
+The app is configured to send outbound messages on macOS via the `messagesSendByHandle` tool in `@easynet/agent-tool-buildin`.
+
+## Prerequisites
+
+- Node.js >= 18
+- macOS with Messages.app signed in
+- Automation permission granted for your terminal/Node process to control Messages.app
+- Ollama (or another OpenAI-compatible endpoint) for the LLM
+
+## Setup
+
+```bash
+cd apps/imessagebot
+npm install
+npm run build
+```
+
+## Usage
+
+```bash
+npm run react
+npm run deep
+node dist/index.js react "Send hello to +1234567890"
+```
+
+## Config
+
+- `config/app.yaml`: app name, paths, and bot prompts
+- `config/agents/shared/model.yaml`: LLM + embedding models config
+- `config/agents/shared/memory.yaml`: memory backend config
+- `config/agents/shared/tool.yaml`: tool config

package/apps/imessagebot/config/.agent/cache/easynet/agent-tool-buildin/0.0.45/README.md

@@ -0,0 +1,33 @@
+# @easynet/agent-tool-buildin
+
+内置工具扩展包，配合 `@easynet/agent-tool` 使用。
+
+## 最小使用方式
+
+在 `tool.yaml` 中添加该包：
+
+```yaml
+tools:
+  sandboxedPath: .
+  allowedHosts: []
+  blockedHosts: []
+  list:
+    - npm:@easynet/agent-tool-buildin
+```
+
+## 常用最小工具集（可选）
+
+```yaml
+tools:
+  sandboxedPath: .
+  allowedHosts: [api.github.com]
+  blockedHosts: []
+  list:
+    - npm:@easynet/agent-tool-buildin#fs.readText
+    - npm:@easynet/agent-tool-buildin#fs.writeText
+    - npm:@easynet/agent-tool-buildin#http.fetchJson
+```
+
+说明：
+- `fs.*` 受 `sandboxedPath` 限制
+- `http.*` 受 `allowedHosts` / `blockedHosts` 限制