@botbotgo/runtime 1.0.0

package/src/runtime/providers/backendResolver.ts

@@ -0,0 +1,127 @@
+import { LocalShellBackendService } from "./localShellBackend.js";
+import { requireModuleFromWorkspace } from "./shared/moduleFallback.js";
+
+interface BackendFactoryLike {
+  (options?: Record<string, unknown>): unknown | Promise<unknown>;
+}
+
+interface BackendConstructorLike {
+  new (options?: Record<string, unknown>): unknown;
+  create?: BackendFactoryLike;
+}
+
+type BackendModuleLike = Record<string, unknown>;
+
+export interface AgentBackendConfig {
+  /**
+   * Built-in selector:
+   * - local_shell (default)
+   * - deepagents_export
+   * - module_export
+   */
+  type?: "local_shell" | "deepagents_export" | "module_export";
+  /** Export name when type=deepagents_export/module_export. */
+  exportName?: string;
+  /** Module path when type=module_export (resolved from workspace root). */
+  module?: string;
+  /** Factory method name. Default: create */
+  createMethod?: string;
+  /** Backend constructor/factory options passthrough. */
+  options?: Record<string, unknown>;
+  /** Convenience overrides for local_shell. */
+  inheritEnv?: boolean;
+  timeoutMs?: number;
+  maxOutputBytes?: number;
+}
+
+export class BackendResolver {
+  public static async create(rootDir: string, config: AgentBackendConfig | undefined): Promise<unknown> {
+    const type = config?.type ?? "local_shell";
+
+    if (type === "local_shell") {
+      const localOptions = config?.options ?? {};
+      return LocalShellBackendService.create(rootDir, {
+        inheritEnv:
+          typeof config?.inheritEnv === "boolean"
+            ? config.inheritEnv
+            : typeof localOptions.inheritEnv === "boolean"
+              ? localOptions.inheritEnv
+              : undefined,
+        timeout:
+          typeof config?.timeoutMs === "number"
+            ? config.timeoutMs
+            : typeof localOptions.timeout === "number"
+              ? localOptions.timeout
+              : typeof localOptions.timeoutMs === "number"
+                ? localOptions.timeoutMs
+                : undefined,
+        maxOutputBytes:
+          typeof config?.maxOutputBytes === "number"
+            ? config.maxOutputBytes
+            : typeof localOptions.maxOutputBytes === "number"
+              ? localOptions.maxOutputBytes
+              : undefined,
+      });
+    }
+
+    if (type === "deepagents_export") {
+      const exportName = config?.exportName?.trim();
+      if (!exportName) {
+        throw new Error("Backend config error: `exportName` is required for type=deepagents_export");
+      }
+      return BackendResolver.createFromModule(rootDir, "deepagents", exportName, config);
+    }
+
+    if (type === "module_export") {
+      const moduleName = config?.module?.trim();
+      const exportName = config?.exportName?.trim();
+      if (!moduleName || !exportName) {
+        throw new Error("Backend config error: `module` and `exportName` are required for type=module_export");
+      }
+      return BackendResolver.createFromModule(rootDir, moduleName, exportName, config);
+    }
+
+    throw new Error(
+      `Backend config error: unsupported backend type '${String(type)}'. ` +
+      "Use local_shell | deepagents_export | module_export."
+    );
+  }
+
+  private static async createFromModule(
+    rootDir: string,
+    moduleName: string,
+    exportName: string,
+    config: AgentBackendConfig | undefined,
+  ): Promise<unknown> {
+    const mod = requireModuleFromWorkspace<BackendModuleLike>(rootDir, moduleName);
+    const target = mod[exportName];
+
+    if (!target) {
+      const available = Object.keys(mod).filter((key) => /backend/i.test(key)).sort();
+      const hint = available.length > 0 ? ` Available backend-like exports: ${available.join(", ")}` : "";
+      throw new Error(`Backend config error: export '${exportName}' not found in module '${moduleName}'.${hint}`);
+    }
+
+    const createMethod = config?.createMethod?.trim() || "create";
+    const options = {
+      rootDir,
+      inheritEnv: config?.inheritEnv,
+      timeout: config?.timeoutMs,
+      maxOutputBytes: config?.maxOutputBytes,
+      ...(config?.options ?? {}),
+    };
+
+    if (typeof target === "function") {
+      const candidate = target as BackendConstructorLike;
+      const factory = (candidate as unknown as Record<string, unknown>)[createMethod];
+      if (typeof factory === "function") {
+        return (factory as BackendFactoryLike).call(candidate, options);
+      }
+      return new candidate(options);
+    }
+
+    throw new Error(
+      `Backend config error: export '${exportName}' from module '${moduleName}' is not a constructor/factory.`,
+    );
+  }
+}

package/src/runtime/providers/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Runtime provider adapters that resolve host-installed dependencies
+ * and assemble concrete model/backend bindings.
+ */
+export { OpenAILocalAgentService } from "./openaiLocalAgent.js";
+export type {
+  CreateOpenAILocalAgentOptions,
+  OpenAILocalAgentParts,
+} from "./openaiLocalAgent.js";
+export { OpenAIDeepAgentService } from "./openaiDeepAgent.js";
+export type {
+  CreateOpenAIDeepAgentOptions,
+  CreateOpenAIDeepAgentResult,
+} from "./openaiDeepAgent.js";
+export { LocalShellBackendService } from "./localShellBackend.js";
+export { BackendResolver } from "./backendResolver.js";
+export type { AgentBackendConfig } from "./backendResolver.js";
+export { LangchainRuntimeBindingsResolver } from "./langchainRuntime.js";
+export type { LangchainRuntimeBindings } from "./langchainRuntime.js";

package/src/runtime/providers/langchainRuntime.ts

@@ -0,0 +1,67 @@
+import type { CreateAgentToolMiddlewareOptions } from "../agentMiddleware.js";
+import { requireModuleFromWorkspace } from "./shared/moduleFallback.js";
+
+export interface LangchainRuntimeBindings {
+  createMiddleware: CreateAgentToolMiddlewareOptions["createMiddleware"];
+  ToolMessage: CreateAgentToolMiddlewareOptions["ToolMessage"];
+}
+
+class FallbackToolMessage {
+  public readonly content: string;
+  public readonly tool_call_id: string;
+
+  public constructor(fields: { content: string; tool_call_id: string }) {
+    this.content = fields.content;
+    this.tool_call_id = fields.tool_call_id;
+  }
+}
+
+export class LangchainRuntimeBindingsResolver {
+  public static resolve(rootDir: string): LangchainRuntimeBindings {
+    const createMiddleware = LangchainRuntimeBindingsResolver.resolveCreateMiddleware(
+      rootDir,
+    );
+    const ToolMessage = LangchainRuntimeBindingsResolver.resolveToolMessage(
+      rootDir,
+    );
+
+    return {
+      createMiddleware,
+      ToolMessage,
+    };
+  }
+
+  private static resolveCreateMiddleware(
+    rootDir: string,
+  ): CreateAgentToolMiddlewareOptions["createMiddleware"] {
+    try {
+      const mod = requireModuleFromWorkspace<{
+        createMiddleware?: CreateAgentToolMiddlewareOptions["createMiddleware"];
+      }>(rootDir, "langchain");
+      if (typeof mod.createMiddleware === "function") {
+        return mod.createMiddleware;
+      }
+    } catch {
+      // Ignore and use compatibility fallback.
+    }
+
+    // Compatibility fallback for LangChain variants that do not expose createMiddleware.
+    return ((definition: unknown) => definition) as CreateAgentToolMiddlewareOptions["createMiddleware"];
+  }
+
+  private static resolveToolMessage(
+    rootDir: string,
+  ): CreateAgentToolMiddlewareOptions["ToolMessage"] {
+    try {
+      const mod = requireModuleFromWorkspace<{
+        ToolMessage?: CreateAgentToolMiddlewareOptions["ToolMessage"];
+      }>(rootDir, "@langchain/core/messages");
+      if (typeof mod.ToolMessage === "function") {
+        return mod.ToolMessage;
+      }
+    } catch {
+      // Ignore and use compatibility fallback.
+    }
+    return FallbackToolMessage as unknown as CreateAgentToolMiddlewareOptions["ToolMessage"];
+  }
+}

package/src/runtime/providers/localShellBackend.ts

@@ -0,0 +1,54 @@
+import { requireModuleFromWorkspace } from "./shared/moduleFallback.js";
+
+interface LocalShellBackendConstructorLike {
+  new (options?: {
+    rootDir?: string;
+    inheritEnv?: boolean;
+    timeout?: number;
+    maxOutputBytes?: number;
+  }): unknown;
+  create(options?: {
+    rootDir?: string;
+    inheritEnv?: boolean;
+    timeout?: number;
+    maxOutputBytes?: number;
+  }): Promise<unknown>;
+}
+
+const DEFAULT_BACKEND_TIMEOUT_MS = 15_000;
+
+export interface LocalShellBackendOptions {
+  rootDir?: string;
+  inheritEnv?: boolean;
+  timeout?: number;
+  maxOutputBytes?: number;
+}
+
+export class LocalShellBackendService {
+  public static async create(rootDir: string, options: LocalShellBackendOptions = {}): Promise<unknown> {
+    const {
+      inheritEnv = true,
+      timeout = DEFAULT_BACKEND_TIMEOUT_MS,
+      maxOutputBytes,
+    } = options;
+    const { LocalShellBackend } = requireModuleFromWorkspace<{
+      LocalShellBackend: LocalShellBackendConstructorLike;
+    }>(rootDir, "deepagents");
+
+    if (typeof LocalShellBackend.create === "function") {
+      return LocalShellBackend.create({
+        rootDir,
+        inheritEnv,
+        timeout,
+        maxOutputBytes,
+      });
+    }
+
+    return new LocalShellBackend({
+      rootDir,
+      inheritEnv,
+      timeout,
+      maxOutputBytes,
+    });
+  }
+}

package/src/runtime/providers/openaiDeepAgent.ts

@@ -0,0 +1,17 @@
+import {
+  OpenAILocalAgentService,
+  type CreateOpenAILocalAgentOptions,
+  type OpenAILocalAgentParts,
+} from "./openaiLocalAgent.js";
+
+export interface CreateOpenAIDeepAgentOptions extends CreateOpenAILocalAgentOptions {}
+
+export interface CreateOpenAIDeepAgentResult extends OpenAILocalAgentParts {}
+
+export class OpenAIDeepAgentService {
+  public static async create(
+    options: CreateOpenAIDeepAgentOptions,
+  ): Promise<CreateOpenAIDeepAgentResult> {
+    return OpenAILocalAgentService.create(options);
+  }
+}

package/src/runtime/providers/openaiLocalAgent.ts

@@ -0,0 +1,35 @@
+import { AgentProbe } from "./shared/agentProbe.js";
+import { OpenAILocalAgentFactory, type CreateOpenAILocalAgentOptions, type OpenAILocalAgentParts } from "./openaiLocalAgentFactory.js";
+import { ResourceCloser } from "./shared/resourceCloser.js";
+
+export type { CreateOpenAILocalAgentOptions } from "./openaiLocalAgentFactory.js";
+export interface OpenAILocalAgentPartsWithClose extends OpenAILocalAgentParts {
+  close(): Promise<void>;
+}
+export type { OpenAILocalAgentPartsWithClose as OpenAILocalAgentParts };
+
+export class OpenAILocalAgentService implements OpenAILocalAgentParts {
+  public readonly modelName: string;
+  public readonly model: unknown;
+  public readonly skills: string[];
+  public readonly backend: unknown;
+  public readonly agent: unknown;
+
+  private constructor(parts: OpenAILocalAgentParts) {
+    this.modelName = parts.modelName;
+    this.model = parts.model;
+    this.skills = parts.skills;
+    this.backend = parts.backend;
+    this.agent = parts.agent;
+  }
+
+  public static async create(options: CreateOpenAILocalAgentOptions): Promise<OpenAILocalAgentService> {
+    const parts = await OpenAILocalAgentFactory.create(options);
+    await AgentProbe.probeStream(parts.agent);
+    return new OpenAILocalAgentService(parts);
+  }
+
+  public async close(): Promise<void> {
+    await ResourceCloser.closeAll([this.agent, this.backend]);
+  }
+}

package/src/runtime/providers/openaiLocalAgentFactory.ts

@@ -0,0 +1,185 @@
+import { resolve } from "node:path";
+import { AgentMemoryStoreAdapter, type AgentMemoryStoreAdapterOptions } from "@botbotgo/memory";
+import { resolveAgentSkillRootsFromToolConfig } from "@botbotgo/kit";
+import { BackendResolver, type AgentBackendConfig } from "./backendResolver.js";
+import {
+  requireAgentRuntimeChatModel,
+  requireAgentRuntimeMemory,
+  requireAgentRuntimeTools,
+} from "../context/agentContext.js";
+import { requireModuleFromWorkspace } from "./shared/moduleFallback.js";
+
+interface CreateDeepAgentLike {
+  (params: {
+    backend: unknown;
+    skills: string[];
+    model: unknown;
+    tools?: unknown[];
+    systemPrompt?: string;
+    store?: unknown;
+    middleware?: unknown[];
+  }): unknown;
+}
+
+export interface CreateOpenAILocalAgentOptions {
+  rootDir: string;
+  configDir?: string;
+  toolConfigPath?: string;
+  allowedToolNames?: string[];
+  modelConfigPath?: string;
+  modelCheckConnectivity?: boolean;
+  model?: string;
+  systemPrompt?: string;
+  temperature?: number;
+  maxTokens?: number;
+  backend?: AgentBackendConfig;
+  middleware?: unknown[];
+  logger?: (message: string) => void;
+}
+
+export interface OpenAILocalAgentParts {
+  modelName: string;
+  model: unknown;
+  skills: string[];
+  backend: unknown;
+  agent: unknown;
+}
+
+export class OpenAILocalAgentFactory {
+  public static async create(options: CreateOpenAILocalAgentOptions): Promise<OpenAILocalAgentParts> {
+    const settings = this.resolveSettings(options);
+    const { createDeepAgent } = requireModuleFromWorkspace<{ createDeepAgent: CreateDeepAgentLike }>(
+      settings.rootDir,
+      "deepagents",
+    );
+    const skills = settings.requestedToolConfigPath
+      ? resolveAgentSkillRootsFromToolConfig({ configFilePath: settings.requestedToolConfigPath })
+      : [];
+    const backend = await BackendResolver.create(settings.rootDir, settings.backendConfig);
+    const tools = this.resolveTools(settings.allowedToolNames, settings.logger);
+    const memoryStore = this.createMemoryStore();
+    const { modelName, model, runtimeModel } = this.resolveModel(settings);
+    this.logIgnoredConfig(settings);
+
+    return {
+      modelName,
+      model,
+      skills,
+      backend,
+      agent: createDeepAgent({
+        backend,
+        skills,
+        model: runtimeModel,
+        tools,
+        systemPrompt: settings.requestedSystemPrompt,
+        store: memoryStore,
+        middleware: settings.middleware,
+      }),
+    };
+  }
+
+  private static resolveSettings(options: CreateOpenAILocalAgentOptions) {
+    return {
+      rootDir: options.rootDir,
+      configDir: options.configDir ?? resolve(options.rootDir, "config"),
+      requestedToolConfigPath: options.toolConfigPath,
+      allowedToolNames: options.allowedToolNames,
+      requestedModelConfigPath: options.modelConfigPath,
+      requestedModelCheckConnectivity: options.modelCheckConnectivity,
+      requestedModel: options.model,
+      requestedSystemPrompt: options.systemPrompt,
+      temperature: options.temperature,
+      requestedMaxTokens: options.maxTokens,
+      backendConfig: options.backend,
+      middleware: options.middleware ?? [],
+      logger: options.logger ?? (() => {}),
+    };
+  }
+
+  private static resolveTools(allowedToolNames: string[] | undefined, logger: (message: string) => void): unknown[] {
+    const tools = requireAgentRuntimeTools<unknown[]>();
+    this.logToolSet("loaded", tools, logger);
+    const filteredTools = this.filterToolsByAllowlist(tools, allowedToolNames);
+    this.logToolSet("filtered", filteredTools, logger);
+    return filteredTools;
+  }
+
+  private static logToolSet(label: string, tools: unknown[], logger: (message: string) => void): void {
+    if (process.env.AGENT_RUNTIME_DEBUG_TOOLS !== "1") return;
+    const names = tools
+      .map((tool) => (tool as { name?: unknown })?.name)
+      .filter((name): name is string => typeof name === "string");
+    logger(`[tools] ${label} count=${names.length}`);
+    logger(`[tools] ${label} sample=${names.slice(0, 20).join(", ")}`);
+  }
+
+  private static createMemoryStore(): AgentMemoryStoreAdapter {
+    const memoryClient = requireAgentRuntimeMemory<AgentMemoryStoreAdapterOptions["agentMemory"]>();
+    return new AgentMemoryStoreAdapter({ agentMemory: memoryClient });
+  }
+
+  private static resolveModel(settings: ReturnType<typeof OpenAILocalAgentFactory.resolveSettings>) {
+    const model = requireAgentRuntimeChatModel<unknown>();
+    const modelName = settings.requestedModel ?? "(context.chatModel)";
+    settings.logger(`[config] model=${modelName}`);
+    return {
+      modelName,
+      model,
+      runtimeModel: this.applyRuntimeOverrides(model, {
+        temperature: settings.temperature,
+        maxTokens: settings.requestedMaxTokens,
+      }),
+    };
+  }
+
+  private static logIgnoredConfig(settings: ReturnType<typeof OpenAILocalAgentFactory.resolveSettings>): void {
+    if (settings.requestedModelConfigPath) {
+      settings.logger(`[config] modelConfigPath is ignored in AgentContext mode: ${settings.requestedModelConfigPath}`);
+    }
+    if (settings.requestedModelCheckConnectivity != null) {
+      settings.logger("[config] modelCheckConnectivity is ignored in AgentContext mode");
+    }
+    if (settings.requestedModel) {
+      settings.logger(`[config] model override is ignored in AgentContext mode: ${settings.requestedModel}`);
+    }
+  }
+
+  private static applyRuntimeOverrides(
+    model: unknown,
+    options: { temperature?: number; maxTokens?: number },
+  ): unknown {
+    const bind = (model as { bind?: (kwargs: Record<string, unknown>) => unknown })?.bind;
+    if (typeof bind !== "function") return model;
+    const kwargs: Record<string, unknown> = {};
+    if (typeof options.temperature === "number") kwargs.temperature = options.temperature;
+    if (typeof options.maxTokens === "number") kwargs.max_tokens = options.maxTokens;
+    return Object.keys(kwargs).length === 0 ? model : bind.call(model, kwargs);
+  }
+
+  private static filterToolsByAllowlist(tools: unknown[], allowedToolNames?: string[]): unknown[] {
+    if (!allowedToolNames?.length) return tools;
+    const matcher = this.buildAllowlistMatcher(allowedToolNames);
+    return tools.filter((tool) => {
+      const name = (tool as { name?: unknown })?.name;
+      return typeof name !== "string" || matcher(name);
+    });
+  }
+
+  private static buildAllowlistMatcher(allowedToolNames: string[]): (name: string) => boolean {
+    const exact = new Set<string>();
+    const short = new Set<string>();
+    for (const raw of allowedToolNames) {
+      const name = raw.trim();
+      if (!name) continue;
+      if (name.includes(".")) exact.add(name);
+      else short.add(name);
+    }
+    return (candidate: string): boolean => {
+      if (exact.has(candidate) || short.has(candidate)) return true;
+      for (const name of short) {
+        if (candidate.endsWith(`.${name}`)) return true;
+      }
+      return false;
+    };
+  }
+}

package/src/runtime/providers/shared/agentProbe.ts

@@ -0,0 +1,24 @@
+export class AgentProbe {
+  public static async probeStream(agent: unknown): Promise<void> {
+    const streamOwner = agent as {
+      stream?: (
+        input: unknown,
+        options: { configurable: { thread_id: string }; streamMode: "values" }
+      ) => Promise<AsyncIterable<unknown>>;
+    };
+    if (typeof streamOwner?.stream !== "function") return;
+
+    const stream = await streamOwner.stream(
+      { messages: [{ role: "user", content: "Probe request: respond briefly." }] },
+      { configurable: { thread_id: `probe-${Date.now()}` }, streamMode: "values" },
+    );
+    const iterator = stream[Symbol.asyncIterator]();
+    await Promise.race([
+      iterator.next(),
+      new Promise<never>((_, reject) => setTimeout(() => reject(new Error("model probe timeout")), 15_000)),
+    ]);
+    if (typeof iterator.return === "function") {
+      await iterator.return().catch(() => {});
+    }
+  }
+}

package/src/runtime/providers/shared/moduleFallback.ts

@@ -0,0 +1,41 @@
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+
+const FALLBACK_PACKAGE_ROOTS = [
+  "..",
+  "../framework/kit",
+  "../agent-runtime",
+  "../kit",
+  "../apps/itermbot",
+  "../apps/imessagebot",
+  "../../framework/kit",
+  "../../agent-runtime",
+  "../../kit",
+  "../../apps/itermbot",
+  "../../apps/imessagebot",
+] as const;
+
+export function requireModuleFromWorkspace<T = unknown>(
+  rootDir: string,
+  moduleName: string,
+): T {
+  const packageRoots = [
+    rootDir,
+    ...FALLBACK_PACKAGE_ROOTS.map((rel) => resolve(rootDir, rel)),
+  ];
+
+  let lastError: unknown;
+  for (const packageRoot of packageRoots) {
+    try {
+      const requireFromRoot = createRequire(resolve(packageRoot, "package.json"));
+      return requireFromRoot(moduleName) as T;
+    } catch (error) {
+      lastError = error;
+    }
+  }
+
+  throw new Error(
+    `Cannot resolve module '${moduleName}' from roots: ${packageRoots.join(", ")}. ` +
+    `Last error: ${String(lastError)}`,
+  );
+}

package/src/runtime/providers/shared/resourceCloser.ts

@@ -0,0 +1,30 @@
+const CLOSE_METHOD_ORDER = ["destroy", "dispose", "shutdown", "close"] as const;
+const CLOSE_TIMEOUT_MS = 1_500;
+
+export class ResourceCloser {
+  public static async closeAll(targets: unknown[]): Promise<void> {
+    await Promise.all(targets.map((target) => this.tryCloseHandle(target)));
+  }
+
+  private static async tryCloseHandle(target: unknown): Promise<void> {
+    if (!target || typeof target !== "object") return;
+    const closeLike = target as Record<string, unknown>;
+    for (const method of CLOSE_METHOD_ORDER) {
+      const fn = closeLike[method];
+      if (typeof fn === "function") {
+        await this.withTimeout(Promise.resolve(fn.call(target)), CLOSE_TIMEOUT_MS).catch(() => {});
+        return;
+      }
+    }
+  }
+
+  private static async withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T | undefined> {
+    return Promise.race([
+      promise,
+      new Promise<undefined>((resolve) => {
+        const timer = setTimeout(() => resolve(undefined), timeoutMs);
+        if (typeof timer.unref === "function") timer.unref();
+      }),
+    ]);
+  }
+}