@botbotgo/runtime 1.0.0

package/test/unit/config/loader.test.ts

@@ -0,0 +1,429 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  loadFromString,
+  loadFromFile,
+  loadFromDirectory,
+  parseResource,
+  parseAllResources,
+  ConfigError,
+} from "../../../src/config/loader.ts";
+import { resolveAgentConfig, buildDeepAgentOptions } from "../../../src/config/resolveRuntimeConfig.ts";
+import { loadAgentRuntimeConfig } from "../../../src/config/runtimeConfigLoader.ts";
+import {
+  isAgentRuntimeConfig,
+  isMemoryConfig,
+  isSkillsConfig,
+  type AgentRuntimeConfigResource,
+  type MemoryConfigResource,
+  type SkillsConfigResource,
+} from "../../../src/config/resources.ts";
+
+function projectRoot(): string {
+  return join(fileURLToPath(import.meta.url), "..", "..", "..", "..");
+}
+
+const MEMORY_YAML = `
+apiVersion: botbotgo.world/v1
+kind: MemoryConfig
+metadata:
+  name: agent-memory-default
+spec:
+  memory:
+    thread:
+      store:
+        type: in_memory
+      allowWrite: true
+      maxItems: 20
+      sessionCompaction:
+        enabled: true
+        maxTokens: 3000
+        keepRecentTurns: 12
+        summaryKey: __session_summary__
+        checkEveryTurns: 3
+    cross_thread:
+      store:
+        type: in_memory
+      allowWrite: true
+      maxItems: 20
+    knowledge:
+      store:
+        type: in_memory
+      allowWrite: true
+      maxItems: 20
+  observability:
+    trace: false
+  privacy:
+    forbiddenMetadataKeys:
+      - password
+      - api_key
+`;
+
+const SKILLS_YAML = `
+apiVersion: botbotgo.world/v1
+kind: SkillsConfig
+metadata:
+  name: default-skills
+spec:
+  skills:
+    file:./skills: {}
+    file:~/.deepagents/agent/skills: {}
+`;
+
+const RUNTIME_YAML = `
+apiVersion: botbotgo.world/v1
+kind: AgentRuntimeConfig
+metadata:
+  name: default-runtime
+spec:
+  artifacts:
+    - key: report
+      path: output/report.html
+  stateDirName: .agent
+  legacyOutputState: true
+  executeTimeoutMs: 45000
+  blockTaskTool: false
+  systemPrompt: You are a runtime test agent.
+  llmIdleTimeoutMs: 300000
+  backend:
+    type: local_shell
+    timeoutMs: 20000
+    maxOutputBytes: 1048576
+  incompleteRunMaxRetries: 2
+  malformedToolCallMaxRetries: 1
+  idleTimeoutMaxRetries: 1
+  heartbeatIntervalMs: 10000
+  debug:
+    run: true
+    workspace: true
+    toolCall: true
+    stream: false
+    close: true
+  eventLogLevel: tools
+`;
+
+describe("config/loader", () => {
+  it("parseResource parses MemoryConfig", () => {
+    const r = parseResource(MEMORY_YAML) as MemoryConfigResource;
+    assert.strictEqual(r.kind, "MemoryConfig");
+    assert.strictEqual(r.metadata.name, "agent-memory-default");
+    assert.strictEqual(r.spec.memory.thread.store.type, "in_memory");
+    assert.strictEqual(r.spec.memory.thread.maxItems, 20);
+    assert.deepStrictEqual(r.spec.privacy?.forbiddenMetadataKeys, [
+      "password",
+      "api_key",
+    ]);
+  });
+
+  it("parseResource parses SkillsConfig", () => {
+    const r = parseResource(SKILLS_YAML) as SkillsConfigResource;
+    assert.strictEqual(r.kind, "SkillsConfig");
+    assert.ok(r.spec.skills["file:./skills"]);
+    assert.ok(r.spec.skills["file:~/.deepagents/agent/skills"]);
+  });
+
+  it("parseResource parses AgentRuntimeConfig", () => {
+    const r = parseResource(RUNTIME_YAML) as AgentRuntimeConfigResource;
+    assert.strictEqual(r.kind, "AgentRuntimeConfig");
+    assert.strictEqual(r.spec.systemPrompt, "You are a runtime test agent.");
+    assert.strictEqual(r.spec.backend?.type, "local_shell");
+    assert.strictEqual(r.spec.malformedToolCallMaxRetries, 1);
+    assert.strictEqual(r.spec.debug?.toolCall, true);
+    assert.strictEqual(r.spec.debug?.stream, false);
+    assert.strictEqual(r.spec.eventLogLevel, "tools");
+  });
+
+  it("loadFromString parses single-doc YAML", () => {
+    const r = loadFromString(MEMORY_YAML);
+    assert.strictEqual(r.kind, "MemoryConfig");
+  });
+
+  it("rejects invalid apiVersion", () => {
+    assert.throws(
+      () =>
+        parseResource(`
+apiVersion: v1
+kind: MemoryConfig
+metadata:
+  name: x
+spec:
+  memory:
+    thread:
+      store: { type: in_memory }
+      allowWrite: true
+      maxItems: 1
+    cross_thread:
+      store: { type: in_memory }
+      allowWrite: true
+      maxItems: 1
+    knowledge:
+      store: { type: in_memory }
+      allowWrite: true
+      maxItems: 1
+`),
+      (err: unknown) => err instanceof ConfigError && err.message.includes("apiVersion")
+    );
+  });
+
+  it("rejects unsupported kind", () => {
+    assert.throws(
+      () =>
+        parseResource(`
+apiVersion: botbotgo.world/v1
+kind: UnknownKind
+metadata:
+  name: x
+spec: {}
+`),
+      (err: unknown) => err instanceof ConfigError && err.message.includes("kind")
+    );
+  });
+
+  it("parseAllResources returns multiple docs", () => {
+    const multi = MEMORY_YAML + "\n---\n" + SKILLS_YAML;
+    const list = parseAllResources(multi);
+    assert.strictEqual(list.length, 2);
+    assert.strictEqual(list[0].kind, "MemoryConfig");
+    assert.strictEqual(list[1].kind, "SkillsConfig");
+  });
+
+  it("loadFromFile loads MemoryConfig from disk", async () => {
+    const path = join(projectRoot(), "config", "examples", "memory.yaml");
+    const r = await loadFromFile(path) as MemoryConfigResource;
+    assert.strictEqual(r.kind, "MemoryConfig");
+    assert.strictEqual(r.metadata.name, "agent-memory-default");
+    assert.strictEqual(r.spec.memory.thread.store.type, "in_memory");
+    assert.deepStrictEqual(r.spec.privacy?.forbiddenMetadataKeys, [
+      "password",
+      "api_key",
+      "secret",
+      "token",
+    ]);
+  });
+
+  it("loadFromDirectory loads all YAML resources from config/examples", async () => {
+    const dir = join(projectRoot(), "config", "examples");
+    const resources = await loadFromDirectory(dir, { ignoreInvalid: true });
+    assert.ok(resources.length >= 3);
+    const kinds = resources.map((r) => r.kind).sort();
+    assert.ok(kinds.includes("AgentRuntimeConfig"));
+    assert.ok(kinds.includes("MemoryConfig"));
+    assert.ok(kinds.includes("SkillsConfig"));
+  });
+
+  it("loadFromFile throws ConfigError with path when file not found", async () => {
+    const path = join(projectRoot(), "config", "nonexistent.yaml");
+    await assert.rejects(
+      async () => loadFromFile(path),
+      (err: unknown) => {
+        return err instanceof ConfigError && err.path === path;
+      }
+    );
+  });
+
+  it("parseResource rejects empty YAML", () => {
+    assert.throws(
+      () => parseResource(""),
+      (err: unknown) => err instanceof ConfigError && err.message.includes("empty")
+    );
+  });
+
+  it("parseResource rejects missing metadata.name", () => {
+    assert.throws(
+      () =>
+        parseResource(`
+apiVersion: botbotgo.world/v1
+kind: MemoryConfig
+metadata: {}
+spec:
+  memory:
+    thread:
+      store: { type: in_memory }
+      allowWrite: true
+      maxItems: 1
+    cross_thread:
+      store: { type: in_memory }
+      allowWrite: true
+      maxItems: 1
+    knowledge:
+      store: { type: in_memory }
+      allowWrite: true
+      maxItems: 1
+`),
+      (err: unknown) => err instanceof ConfigError
+    );
+  });
+
+  it("parseAllResources with ignoreInvalid skips invalid doc and returns valid ones", () => {
+    const yaml = `
+apiVersion: botbotgo.world/v1
+kind: MemoryConfig
+metadata:
+  name: valid
+spec:
+  memory:
+    thread:
+      store: { type: in_memory }
+      allowWrite: true
+      maxItems: 1
+    cross_thread:
+      store: { type: in_memory }
+      allowWrite: true
+      maxItems: 1
+    knowledge:
+      store: { type: in_memory }
+      allowWrite: true
+      maxItems: 1
+---
+apiVersion: v1
+kind: Bad
+metadata: { name: bad }
+spec: {}
+---
+apiVersion: botbotgo.world/v1
+kind: SkillsConfig
+metadata:
+  name: skills
+spec:
+  skills:
+    file:./a: {}
+`;
+    const list = parseAllResources(yaml, { ignoreInvalid: true });
+    assert.strictEqual(list.length, 2);
+    assert.strictEqual(list[0].kind, "MemoryConfig");
+    assert.strictEqual(list[1].kind, "SkillsConfig");
+  });
+
+  it("isMemoryConfig and isSkillsConfig type guards", () => {
+    const memory = parseResource(MEMORY_YAML);
+    const skills = parseResource(SKILLS_YAML);
+    const runtime = parseResource(RUNTIME_YAML);
+    assert.strictEqual(isMemoryConfig(memory), true);
+    assert.strictEqual(isSkillsConfig(memory), false);
+    assert.strictEqual(isAgentRuntimeConfig(memory), false);
+    assert.strictEqual(isSkillsConfig(skills), true);
+    assert.strictEqual(isMemoryConfig(skills), false);
+    assert.strictEqual(isAgentRuntimeConfig(skills), false);
+    assert.strictEqual(isAgentRuntimeConfig(runtime), true);
+  });
+});
+
+describe("deepagents", () => {
+  it("resolveAgentConfig merges MemoryConfig and SkillsConfig", () => {
+    const resources = [
+      parseResource(MEMORY_YAML) as MemoryConfigResource,
+      parseResource(SKILLS_YAML) as SkillsConfigResource,
+      parseResource(RUNTIME_YAML) as AgentRuntimeConfigResource,
+    ];
+    const resolved = resolveAgentConfig(resources);
+    assert.ok(resolved.memory);
+    assert.strictEqual(resolved.memory!.thread.store.type, "in_memory");
+    assert.strictEqual(resolved.memory!.thread.sessionCompaction?.summaryKey, "__session_summary__");
+    assert.deepStrictEqual(resolved.skills, []);
+    assert.strictEqual(resolved.observability.trace, false);
+    assert.deepStrictEqual(resolved.privacy.forbiddenMetadataKeys, ["password", "api_key"]);
+    assert.strictEqual(resolved.runtime.backend?.type, "local_shell");
+    assert.strictEqual(resolved.runtime.backend?.timeoutMs, 20000);
+    assert.strictEqual(resolved.runtime.incompleteRunMaxRetries, 2);
+    assert.strictEqual(resolved.runtime.executeTimeoutMs, 45000);
+    assert.strictEqual(resolved.runtime.systemPrompt, "You are a runtime test agent.");
+    assert.strictEqual(resolved.runtime.llmIdleTimeoutMs, 300000);
+    assert.strictEqual(resolved.runtime.heartbeatIntervalMs, 10000);
+    assert.strictEqual(resolved.runtime.debug?.run, true);
+    assert.strictEqual(resolved.runtime.debug?.stream, false);
+    assert.strictEqual(resolved.runtime.eventLogLevel, "tools");
+    assert.strictEqual(resolved.runtime.artifacts?.[0]?.path, "output/report.html");
+  });
+
+  it("buildDeepAgentOptions returns skills array and _resolved", () => {
+    const resources = [
+      parseResource(SKILLS_YAML) as SkillsConfigResource,
+    ];
+    const resolved = resolveAgentConfig(resources);
+    const opts = buildDeepAgentOptions(resolved);
+    assert.deepStrictEqual(opts.skills, []);
+    assert.strictEqual(opts._resolved, resolved);
+  });
+
+  it("resolveAgentConfig with empty resources returns defaults", () => {
+    const resolved = resolveAgentConfig([]);
+    assert.strictEqual(resolved.skills.length, 0);
+    assert.strictEqual(resolved.memory, null);
+    assert.strictEqual(resolved.observability.trace, false);
+    assert.deepStrictEqual(resolved.privacy.forbiddenMetadataKeys, []);
+    assert.deepStrictEqual(resolved.runtime, {});
+  });
+
+  it("resolveAgentConfig with only MemoryConfig has no skills", () => {
+    const resources = [parseResource(MEMORY_YAML) as MemoryConfigResource];
+    const resolved = resolveAgentConfig(resources);
+    assert.deepStrictEqual(resolved.skills, []);
+    assert.ok(resolved.memory);
+    assert.deepStrictEqual(resolved.privacy.forbiddenMetadataKeys, ["password", "api_key"]);
+  });
+
+  it("resolveAgentConfig with only SkillsConfig has no memory", () => {
+    const resources = [parseResource(SKILLS_YAML) as SkillsConfigResource];
+    const resolved = resolveAgentConfig(resources);
+    assert.strictEqual(resolved.memory, null);
+    assert.deepStrictEqual(resolved.skills, []);
+  });
+
+  it("resolveAgentConfig ignores SkillsConfig source resolution", () => {
+    const skills2 = `
+apiVersion: botbotgo.world/v1
+kind: SkillsConfig
+metadata:
+  name: extra
+spec:
+  skills:
+    file:/extra/skills: {}
+`;
+    const resources = [
+      parseResource(SKILLS_YAML) as SkillsConfigResource,
+      parseResource(skills2) as SkillsConfigResource,
+    ];
+    const resolved = resolveAgentConfig(resources);
+    assert.deepStrictEqual(resolved.skills, []);
+  });
+
+  it("buildDeepAgentOptions with no skills returns empty skills array", () => {
+    const resolved = resolveAgentConfig([]);
+    const opts = buildDeepAgentOptions(resolved);
+    assert.deepStrictEqual(opts.skills, []);
+    assert.strictEqual(opts._resolved.memory, null);
+  });
+});
+
+describe("loadAgentRuntimeConfig", () => {
+  it("loads from configDir without resolving skill roots", async () => {
+    const root = projectRoot();
+    const configDir = join(root, "config", "examples");
+    const runtimeConfig = await loadAgentRuntimeConfig({
+      configDir,
+      ignoreInvalid: true,
+    });
+    assert.ok(runtimeConfig.resolved);
+    assert.ok(runtimeConfig.resolved.memory);
+    assert.deepStrictEqual(runtimeConfig.resolved.skills, []);
+  });
+
+  it("accepts pre-loaded resources without resolving SkillsConfig entries", async () => {
+    const resources = [
+      parseResource(SKILLS_YAML) as SkillsConfigResource,
+    ];
+    const runtimeConfig = await loadAgentRuntimeConfig({
+      resources,
+    });
+    assert.strictEqual(runtimeConfig.resolved.skills.length, 0);
+  });
+
+  it("throws when no config source provided", async () => {
+    await assert.rejects(
+      async () => loadAgentRuntimeConfig({}),
+      (err: unknown) => (err as Error).message.includes("configPath") || (err as Error).message.includes("configDir") || (err as Error).message.includes("resources")
+    );
+  });
+});

package/test/unit/runtime/agentContext.test.ts

@@ -0,0 +1,23 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { AgentContextTokens, getDefaultAgentContext } from "@botbotgo/common/context";
+import {
+  requireAgentRuntimeChatModel,
+  requireAgentRuntimeMemory,
+  requireAgentRuntimeTools,
+} from "../../../src/runtime/context/agentContext.ts";
+
+test("agent-runtime2 reads dependencies from AgentContext", () => {
+  const context = getDefaultAgentContext();
+  const chatModel = { kind: "chat" };
+  const memory = { kind: "memory" };
+  const tools = [{ name: "tool-a" }];
+
+  context.set(AgentContextTokens.ChatModel, chatModel);
+  context.set(AgentContextTokens.Memory, memory);
+  context.set(AgentContextTokens.Tools, tools);
+
+  assert.equal(requireAgentRuntimeChatModel(), chatModel);
+  assert.equal(requireAgentRuntimeMemory(), memory);
+  assert.equal(requireAgentRuntimeTools(), tools);
+});

package/test/unit/runtime/agentRuntime.test.ts

@@ -0,0 +1,99 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createAgentEventBus } from "@botbotgo/common/events";
+import { AgentRuntimeService } from "../../../src/runtime/runtimeService.ts";
+import { AgentRuntimeEventPublisher } from "../../../src/runtime/events/eventPublisher.ts";
+import { AgentRunExecutor } from "../../../src/runtime/execution/agentRunExecutor.ts";
+
+test("runtime eventListener setter replaces subscriptions", () => {
+  const runtime = new AgentRuntimeService({
+    rootDir: "/tmp/runtime",
+    runLogger: () => {},
+    events: new AgentRuntimeEventPublisher(createAgentEventBus()),
+    runtimeConfig: {} as never,
+    middleware: {},
+    workspace: {
+      prepareRun: (() => {
+        throw new Error("not used");
+      }) as never,
+    } as never,
+    runtimeAgent: {
+      agent: {},
+      close: async () => {},
+    } as never,
+  });
+
+  const received: string[] = [];
+  runtime.eventListener = (event) => {
+    received.push(`first:${event.name}`);
+  };
+  runtime.events.publish({
+    name: "event.one",
+    from: "a",
+    to: "b",
+  });
+
+  runtime.eventListener = (event) => {
+    received.push(`second:${event.name}`);
+  };
+  runtime.events.publish({
+    name: "event.two",
+    from: "a",
+    to: "b",
+  });
+
+  runtime.eventListener = undefined;
+  runtime.events.publish({
+    name: "event.three",
+    from: "a",
+    to: "b",
+  });
+
+  assert.deepEqual(received, ["first:event.one", "second:event.two"]);
+});
+
+test("AgentRunExecutor applies custom artifactValidator without use-case-specific framework logic", async () => {
+  const rootDir = join(tmpdir(), `agent-runtime2-validator-${Date.now()}`);
+  const outputDir = join(rootDir, "output");
+  const artifactPath = join(outputDir, "result.json");
+  await mkdir(outputDir, { recursive: true });
+  await writeFile(artifactPath, "{\"ok\":true}\n", "utf8");
+
+  const executor = new AgentRunExecutor({
+    rootDir,
+    workspace: {
+      artifactFiles: { result: artifactPath },
+      runStateFile: join(rootDir, ".agent", "run-state.json"),
+      todosFile: join(rootDir, ".agent", "todos.json"),
+      prepareRun: async () => ({
+        threadId: "t-1",
+        input: { messages: [] },
+        config: { configurable: { thread_id: "t-1" } },
+        previousState: undefined,
+        start: async () => {},
+        update: async () => {},
+        finish: async () => {},
+      }),
+    } as never,
+    events: new AgentRuntimeEventPublisher(createAgentEventBus()),
+    runLogger: () => {},
+    artifactValidator: () => false,
+  });
+
+  await assert.rejects(
+    executor.runStream({
+      prompt: "write to output/result.json",
+      incompleteRunMaxRetries: 0,
+      summarizeChunk: () => "done",
+      createStream: async function* () {
+        yield { ok: true };
+      },
+    }),
+    /Run ended before completion/,
+  );
+
+  await rm(rootDir, { recursive: true, force: true });
+});

package/test/unit/runtime/consoleHumanLoop.test.ts

@@ -0,0 +1,52 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { ConsoleHumanLoopService } from "../../../src/runtime/human-loop/consoleHumanLoop.ts";
+import type { HumanLoopRequest } from "../../../src/runtime/human-loop/humanLoop.ts";
+
+const baseRequest: HumanLoopRequest = {
+  id: "req-1",
+  kind: "tool_approval",
+  threadId: "thread-1",
+  toolCallId: "call-1",
+  toolName: "execute",
+  title: "Approval required for execute",
+  description: "Command: printf unsafe",
+  args: { command: "printf unsafe" },
+  rootDir: "/workspace",
+  createdAt: "2026-03-06T00:00:00.000Z",
+  riskLevel: "high",
+};
+
+test("ConsoleHumanLoopService approves after prompt", async () => {
+  const questions: string[] = [];
+  const lines: string[] = [];
+  const service = new ConsoleHumanLoopService({
+    prompt: async (question) => {
+      questions.push(question);
+      return "a";
+    },
+    writer: (line) => {
+      lines.push(line);
+    },
+  });
+
+  const decision = await service.request(baseRequest);
+
+  assert.equal(decision.action, "approve");
+  assert.equal(questions[0], "Approve, reject, or revise? [a/r/e]: ");
+  assert.match(lines.join("\n"), /\[human-loop\] Approval required for execute/);
+});
+
+test("ConsoleHumanLoopService revises args from JSON input", async () => {
+  const answers = ["e", "{\"command\":\"printf safe\"}", "Use safe command."];
+  const service = new ConsoleHumanLoopService({
+    prompt: async () => answers.shift() ?? "",
+    writer: () => {},
+  });
+
+  const decision = await service.request(baseRequest);
+
+  assert.equal(decision.action, "revise");
+  assert.deepEqual(decision.revisedArgs, { command: "printf safe" });
+  assert.equal(decision.message, "Use safe command.");
+});

package/test/unit/runtime/events.test.ts

@@ -0,0 +1,11 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createAgentEventBus } from "@botbotgo/common";
+import { AgentRuntimeEventPublisher } from "../../../src/runtime/events/eventPublisher.ts";
+
+test("runtime event publisher reuses AgentContext event bus", () => {
+  const eventBus = createAgentEventBus();
+  const publisher = new AgentRuntimeEventPublisher();
+
+  assert.equal(publisher.bus, eventBus);
+});

package/test/unit/runtime/globalContext.test.ts

@@ -0,0 +1,34 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  clearAgentRuntimeGlobalContext,
+  getAgentRuntimeGlobal,
+  getOrRegisterAgentRuntimeGlobal,
+  registerAgentRuntimeGlobal,
+} from "../../../src/runtime/context/globalContext.ts";
+
+test("global context shares registered values", () => {
+  clearAgentRuntimeGlobalContext();
+  const value = { ok: true };
+
+  registerAgentRuntimeGlobal("runtime:test:value", value);
+
+  assert.equal(getAgentRuntimeGlobal("runtime:test:value"), value);
+});
+
+test("global context reuses lazily registered values", () => {
+  clearAgentRuntimeGlobalContext();
+  let created = 0;
+
+  const first = getOrRegisterAgentRuntimeGlobal("runtime:test:lazy", () => {
+    created += 1;
+    return { created };
+  });
+  const second = getOrRegisterAgentRuntimeGlobal("runtime:test:lazy", () => {
+    created += 1;
+    return { created };
+  });
+
+  assert.equal(created, 1);
+  assert.equal(first, second);
+});