@botbotgo/runtime 1.0.0

package/example/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "agent-runtime2-example",
+  "version": "0.1.0",
+  "description": "Standalone example app using agent-runtime2 with real LLM",
+  "type": "module",
+  "main": "index.ts",
+  "scripts": {
+    "build": "tsc --incremental --tsBuildInfoFile .tsbuildinfo",
+    "start": "node --import tsx index.ts",
+    "start:prod": "npm --prefix .. run build && npm run build && node dist/index.js",
+    "report:serve": "node serve-output.mjs",
+    "dev": "tsx index.ts",
+    "test": "npm run build"
+  },
+  "dependencies": {
+    "@botbotgo/runtime": "file:..",
+    "@langchain/core": "^1.1.31",
+    "@langchain/openai": "^1.2.12",
+    "deepagents": "^1.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}

package/example/serve-output.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { createServer } from "node:http";
+import { readFileSync, statSync } from "node:fs";
+import { extname, join, normalize, resolve } from "node:path";
+
+const rootDir = resolve(process.cwd(), "output");
+const port = Number(process.env.REPORT_PORT || 8787);
+const host = process.env.REPORT_HOST || "127.0.0.1";
+
+const contentTypes = new Map([
+  [".html", "text/html; charset=utf-8"],
+  [".json", "application/json; charset=utf-8"],
+  [".css", "text/css; charset=utf-8"],
+  [".js", "application/javascript; charset=utf-8"],
+  [".txt", "text/plain; charset=utf-8"],
+]);
+
+function safePath(urlPath) {
+  const decoded = decodeURIComponent(urlPath.split("?")[0] || "/");
+  const normalized = normalize(decoded).replace(/^(\.\.(\/|\\|$))+/, "");
+  const rel = normalized === "/" ? "company-report.html" : normalized.replace(/^[/\\]/, "");
+  const abs = resolve(rootDir, rel);
+  if (!abs.startsWith(rootDir)) {
+    throw new Error("Path traversal blocked");
+  }
+  return abs;
+}
+
+const server = createServer((req, res) => {
+  try {
+    const abs = safePath(req.url || "/");
+    const st = statSync(abs);
+    if (!st.isFile()) {
+      res.statusCode = 404;
+      res.end("Not Found");
+      return;
+    }
+    const body = readFileSync(abs);
+    const type = contentTypes.get(extname(abs)) || "application/octet-stream";
+    res.setHeader("Content-Type", type);
+    res.statusCode = 200;
+    res.end(body);
+  } catch {
+    res.statusCode = 404;
+    res.end("Not Found");
+  }
+});
+
+server.listen(port, host, () => {
+  const url = `http://${host}:${port}/company-report.html`;
+  process.stdout.write(`Report server running at ${url}\n`);
+});

package/example/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "baseUrl": ".",
+    "paths": {
+      "#agent-runtime2": ["../dist/index.d.ts"],
+      "@botbotgo/runtime": ["../dist/index.d.ts"]
+    },
+    "outDir": "dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["index.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@botbotgo/runtime",
+  "version": "1.0.0",
+  "description": "Runtime service and YAML config loader for deepagents-based agent apps",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "preinstall": "node scripts/resolve-deps.js",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && npm run typecheck && node --import tsx --test --test-force-exit test/unit/config/loader.test.ts test/unit/runtime/*.test.ts test/integration/*.test.ts",
+    "test:integration": "npm run build && npm run typecheck && node --import tsx --test --test-force-exit test/integration/*.test.ts",
+    "test:watch": "npm run build && npm run typecheck && node --import tsx --test --watch test/unit/config/loader.test.ts test/unit/runtime/*.test.ts test/integration/*.test.ts",
+    "release": "semantic-release"
+  },
+  "keywords": [
+    "agent",
+    "skills",
+    "deepagents",
+    "langchain",
+    "yaml",
+    "config"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@botbotgo/common": "latest",
+    "@botbotgo/memory": "latest",
+    "@botbotgo/model": "latest",
+    "@botbotgo/kit": "latest"
+  },
+  "devDependencies": {
+    "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^12.0.0",
+    "@semantic-release/release-notes-generator": "^14.0.0",
+    "@langchain/core": "^1.1.31",
+    "@types/node": "^22.10.1",
+    "semantic-release": "^24.2.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "peerDependencies": {
+    "@langchain/core": "^1.1.31",
+    "deepagents": "^1.8.1"
+  },
+  "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    },
+    "deepagents": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/botbotgo/runtime.git"
+  },
+  "homepage": "https://github.com/botbotgo/runtime#readme",
+  "bugs": {
+    "url": "https://github.com/botbotgo/runtime/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/scripts/resolve-deps.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const helperPath = resolve(scriptDir, "../../../scripts/internal-package-refs.mjs");
+const packageJsonPath = resolve(scriptDir, "../package.json");
+
+function fallbackRewriteCurrentPackage() {
+  const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+  let changed = false;
+  const packageDir = resolve(scriptDir, "..");
+
+  for (const section of ["dependencies", "devDependencies", "optionalDependencies"]) {
+    const deps = pkg[section];
+    if (!deps || typeof deps !== "object") continue;
+    for (const [name, version] of Object.entries(deps)) {
+      if (!name.startsWith("@botbotgo/")) continue;
+      if (typeof version !== "string" || !version.startsWith("file:")) continue;
+      if (existsSync(resolve(packageDir, version.slice("file:".length)))) continue;
+      deps[name] = "latest";
+      changed = true;
+      console.log(`[resolve-deps:fallback] ${section}.${name}: ${version} -> ${deps[name]}`);
+    }
+  }
+
+  if (changed) {
+    writeFileSync(packageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`);
+  }
+}
+
+if (!existsSync(helperPath)) {
+  fallbackRewriteCurrentPackage();
+  process.exit(0);
+}
+
+const { syncCurrentPackageFromScript } = await import(pathToFileURL(helperPath).href);
+syncCurrentPackageFromScript(import.meta.url, "auto");

package/src/config/index.ts

@@ -0,0 +1,29 @@
+export {
+  loadFromFile,
+  loadFromDirectory,
+  loadFromString,
+  parseResource,
+  parseAllResources,
+  ConfigError,
+} from "./loader.js";
+export type { LoadOptions } from "./loader.js";
+
+export {
+  resolveAgentConfig,
+  buildDeepAgentOptions,
+} from "./resolveRuntimeConfig.js";
+export type {
+  ResolvedAgentConfig,
+  ResolvedMemoryConfig,
+  ResolvedAgentRuntimeConfig,
+  MemoryStoreResolved,
+} from "./resolveRuntimeConfig.js";
+
+export {
+  loadAgentRuntimeConfig,
+  AgentRuntimeConfigService,
+} from "./runtimeConfigLoader.js";
+export type {
+  LoadAgentRuntimeConfigOptions,
+  AgentRuntimeConfigResult,
+} from "./runtimeConfigLoader.js";

package/src/config/loader.ts

@@ -0,0 +1,174 @@
+/**
+ * Load K8s-style YAML config from file, directory, or string.
+ */
+
+import {
+  loadYamlFile,
+  parseYamlContent,
+} from "@botbotgo/common/config";
+import { readFile, readdir } from "node:fs/promises";
+import { join, extname } from "node:path";
+import type { Resource } from "./resources.js";
+
+const YAML_EXTS = [".yaml", ".yml"];
+const SUPPORTED_API = "botbotgo.world/v1";
+const SUPPORTED_KINDS = ["MemoryConfig", "SkillsConfig", "AgentRuntimeConfig"] as const;
+
+export interface LoadOptions {
+  /** If true, skip invalid documents and continue; default false */
+  ignoreInvalid?: boolean;
+  /** Optional base directory for resolving relative paths in config (e.g. skill paths) */
+  baseDir?: string;
+}
+
+export class ConfigError extends Error {
+  constructor(
+    message: string,
+    public readonly path?: string,
+    public readonly cause?: unknown
+  ) {
+    super(message);
+    this.name = "ConfigError";
+  }
+}
+
+function splitYamlDocuments(yamlContent: string): string[] {
+  return yamlContent
+    .split(/^---(?:\s+#.*)?\s*$/m)
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function hasRequiredFields(doc: unknown): doc is Resource<string, unknown> {
+  if (!isRecord(doc)) return false;
+  if (typeof doc.apiVersion !== "string" || typeof doc.kind !== "string")
+    return false;
+  if (!isRecord(doc.metadata) || typeof doc.metadata.name !== "string")
+    return false;
+  if (!(typeof doc.spec === "object" && doc.spec !== null)) return false;
+  return true;
+}
+
+function validateResource(doc: unknown): Resource<string, unknown> {
+  if (doc === undefined || doc === null)
+    throw new ConfigError("YAML document is empty");
+  if (!hasRequiredFields(doc))
+    throw new ConfigError(
+      "Invalid resource: missing or invalid apiVersion, kind, metadata.name, or spec"
+    );
+  if (doc.apiVersion !== SUPPORTED_API)
+    throw new ConfigError(
+      `Unsupported apiVersion: ${doc.apiVersion}. Expected ${SUPPORTED_API}`
+    );
+  if (!SUPPORTED_KINDS.includes(doc.kind as (typeof SUPPORTED_KINDS)[number]))
+    throw new ConfigError(
+      `Unsupported kind: ${doc.kind}. Supported: ${SUPPORTED_KINDS.join(", ")}`
+    );
+  return doc as Resource<string, unknown>;
+}
+
+/**
+ * Parse a single YAML document into a typed Resource.
+ * Does not validate spec shape per kind; use validators if needed.
+ */
+export function parseResource(yamlContent: string): Resource<string, unknown> {
+  return validateResource(parseYamlContent(yamlContent));
+}
+
+/**
+ * Parse YAML that may contain multiple documents (--- separated).
+ * Returns the first valid resource; throws if none valid.
+ */
+export function parseAllResources(
+  yamlContent: string,
+  options: LoadOptions = {}
+): Resource<string, unknown>[] {
+  const out: Resource<string, unknown>[] = [];
+  const docs = splitYamlDocuments(yamlContent);
+
+  for (let i = 0; i < docs.length; i++) {
+    try {
+      out.push(validateResource(parseYamlContent(docs[i])));
+    } catch (e) {
+      if (!options.ignoreInvalid) throw e;
+    }
+  }
+  return out;
+}
+
+/**
+ * Load a single resource from a file path.
+ */
+export async function loadFromFile(
+  filePath: string,
+  options: LoadOptions = {}
+): Promise<Resource<string, unknown>> {
+  try {
+    const doc = await loadYamlFile(filePath);
+    if (doc === undefined) {
+      throw new ConfigError(`Failed to read file: ${filePath}`, filePath);
+    }
+    return validateResource(doc);
+  } catch (e) {
+    if (e instanceof ConfigError) {
+      throw new ConfigError(e.message, filePath, e.cause);
+    }
+    if ((e as { code?: string } | undefined)?.code === "ENOENT") {
+      throw new ConfigError(`Failed to read file: ${filePath}`, filePath, e);
+    }
+    throw new ConfigError(String(e), filePath, e);
+  }
+}
+
+/**
+ * Load all K8s-style resources from a directory.
+ * Scans for .yaml/.yml files (non-recursive by default).
+ */
+export async function loadFromDirectory(
+  dirPath: string,
+  options: LoadOptions & { recursive?: boolean } = {}
+): Promise<Resource<string, unknown>[]> {
+  const { recursive = false, ...loadOpts } = options;
+  const entries = await readdir(dirPath, { withFileTypes: true }).catch((e) => {
+    throw new ConfigError(`Failed to read directory: ${dirPath}`, dirPath, e);
+  });
+  const results: Resource<string, unknown>[] = [];
+  for (const ent of entries) {
+    const full = join(dirPath, ent.name);
+    if (ent.isDirectory() && recursive) {
+      const sub = await loadFromDirectory(full, options);
+      results.push(...sub);
+    }
+    if (!ent.isFile() || !YAML_EXTS.includes(extname(ent.name))) continue;
+    try {
+      const content = await readFile(full, "utf-8");
+      const resources = parseAllResources(content, loadOpts);
+      results.push(...resources);
+    } catch (e) {
+      if (!loadOpts.ignoreInvalid)
+        throw new ConfigError(String(e), full, e);
+    }
+  }
+  return results;
+}
+
+/**
+ * Parse a single resource from a YAML string.
+ */
+export function loadFromString(
+  content: string,
+  options: LoadOptions = {}
+): Resource<string, unknown> {
+  const multi = content.includes("---");
+  if (multi) {
+    const list = parseAllResources(content, options);
+    if (list.length === 0)
+      throw new ConfigError("No valid resource found in multi-document YAML");
+    return list[0];
+  }
+  return parseResource(content);
+}

package/src/config/resolveRuntimeConfig.ts

@@ -0,0 +1,160 @@
+/**
+ * Map loaded K8s-style configs to options suitable for deepagents (createDeepAgent).
+ * Supports MemoryConfig, SkillsConfig, and AgentRuntimeConfig; memory shape is exposed for app use
+ * until deepagents exposes a matching memory API.
+ */
+
+import type {
+  AgentBackendConfigSpec,
+  AgentRuntimeConfigResource,
+  KnownResource,
+  MemoryConfigResource,
+} from "./resources.js";
+import { isAgentRuntimeConfig, isMemoryConfig } from "./resources.js";
+
+export interface ResolvedAgentConfig {
+  /** Skill source paths to pass to createDeepAgent({ skills }) */
+  skills: string[];
+  /** Resolved memory config (thread/cross_thread/knowledge). Use for your own store/checkpointer or when deepagents supports it. */
+  memory: ResolvedMemoryConfig | null;
+  /** Observability and privacy from MemoryConfig, if present */
+  observability: { trace: boolean };
+  privacy: { forbiddenMetadataKeys: string[] };
+  /** Runtime defaults from AgentRuntimeConfig, if present */
+  runtime: ResolvedAgentRuntimeConfig;
+}
+
+export interface ResolvedMemoryConfig {
+  thread: MemoryStoreResolved;
+  cross_thread: MemoryStoreResolved;
+  knowledge: MemoryStoreResolved;
+}
+
+export interface MemoryStoreResolved {
+  store: { type: string; options?: Record<string, unknown> };
+  allowWrite: boolean;
+  maxItems: number;
+  sessionCompaction?: {
+    enabled: boolean;
+    maxTokens: number;
+    keepRecentTurns: number;
+    summaryKey: string;
+    checkEveryTurns: number;
+  };
+}
+
+export interface ResolvedAgentRuntimeConfig {
+  artifacts?: Array<{
+    key: string;
+    path: string;
+  }>;
+  stateDirName?: string;
+  legacyOutputState?: boolean;
+  executeTimeoutMs?: number;
+  blockTaskTool?: boolean;
+  systemPrompt?: string;
+  llmIdleTimeoutMs?: number;
+  backend?: AgentBackendConfigSpec;
+  incompleteRunMaxRetries?: number;
+  emptyRunMaxRetries?: number;
+  malformedToolCallMaxRetries?: number;
+  idleTimeoutMaxRetries?: number;
+  heartbeatIntervalMs?: number;
+  debug?: {
+    run?: boolean;
+    workspace?: boolean;
+    toolCall?: boolean;
+    stream?: boolean;
+    close?: boolean;
+  };
+  eventLogLevel?: "silent" | "lifecycle" | "tools" | "verbose";
+}
+
+const DEFAULT_OBSERVABILITY = { trace: false };
+const DEFAULT_PRIVACY = { forbiddenMetadataKeys: [] as string[] };
+
+/**
+ * Reduce an array of loaded resources into a single ResolvedAgentConfig.
+ * - SkillsConfig: parsed for compatibility, but skill roots are resolved outside this module.
+ * - MemoryConfig: first one wins (by name order or array order); optional merge strategy could be added.
+ */
+export function resolveAgentConfig(resources: KnownResource[]): ResolvedAgentConfig {
+  let skills: string[] = [];
+  let memory: ResolvedMemoryConfig | null = null;
+  let observability = DEFAULT_OBSERVABILITY;
+  let privacy = DEFAULT_PRIVACY;
+  let runtime: ResolvedAgentRuntimeConfig = {};
+
+  for (const r of resources) {
+    if (isMemoryConfig(r)) {
+      if (!memory) {
+        memory = {
+          thread: resolveStore(r.spec.memory.thread),
+          cross_thread: resolveStore(r.spec.memory.cross_thread),
+          knowledge: resolveStore(r.spec.memory.knowledge),
+        };
+      }
+      if (r.spec.observability) {
+        observability = { trace: r.spec.observability.trace ?? false };
+      }
+      if (r.spec.privacy?.forbiddenMetadataKeys) {
+        privacy = { forbiddenMetadataKeys: [...r.spec.privacy.forbiddenMetadataKeys] };
+      }
+    }
+    if (isAgentRuntimeConfig(r)) {
+      runtime = resolveRuntime(r.spec);
+    }
+  }
+
+  return {
+    skills,
+    memory,
+    observability,
+    privacy,
+    runtime,
+  };
+}
+
+function resolveStore(s: MemoryConfigResource["spec"]["memory"]["thread"]): MemoryStoreResolved {
+  return {
+    store: { type: s.store.type, options: s.store.options },
+    allowWrite: s.allowWrite,
+    maxItems: s.maxItems,
+    sessionCompaction: s.sessionCompaction,
+  };
+}
+
+function resolveRuntime(s: AgentRuntimeConfigResource["spec"]): ResolvedAgentRuntimeConfig {
+  return {
+    artifacts: s.artifacts,
+    stateDirName: s.stateDirName,
+    legacyOutputState: s.legacyOutputState,
+    executeTimeoutMs: s.executeTimeoutMs,
+    blockTaskTool: s.blockTaskTool,
+    systemPrompt: s.systemPrompt,
+    llmIdleTimeoutMs: s.llmIdleTimeoutMs,
+    backend: s.backend,
+    incompleteRunMaxRetries: s.incompleteRunMaxRetries,
+    emptyRunMaxRetries: s.emptyRunMaxRetries,
+    malformedToolCallMaxRetries: s.malformedToolCallMaxRetries,
+    idleTimeoutMaxRetries: s.idleTimeoutMaxRetries,
+    heartbeatIntervalMs: s.heartbeatIntervalMs,
+    debug: s.debug,
+    eventLogLevel: s.eventLogLevel,
+  };
+}
+
+/**
+ * Build options object for createDeepAgent from resolved config.
+ * Pass skills; use resolvedAgentConfig.memory / observability / privacy in your app as needed.
+ */
+export function buildDeepAgentOptions(resolved: ResolvedAgentConfig): {
+  skills: string[];
+  /** Optional: attach to run/config for observability and privacy (app-specific) */
+  _resolved: ResolvedAgentConfig;
+} {
+  return {
+    skills: resolved.skills.length > 0 ? resolved.skills : [],
+    _resolved: resolved,
+  };
+}