@botbotgo/runtime 1.0.0

package/src/config/resources.ts

@@ -0,0 +1,152 @@
+/**
+ * K8s-style resource base: apiVersion, kind, metadata, spec.
+ * Used for MemoryConfig, SkillsConfig, and future resource kinds.
+ */
+
+export const API_GROUP = "botbotgo.world";
+export const API_VERSION = "v1";
+export const API_VERSION_FULL = `${API_GROUP}/${API_VERSION}`;
+
+/** Standard metadata for all resources */
+export interface ObjectMeta {
+  name: string;
+  /** Optional labels (e.g. for filtering) */
+  labels?: Record<string, string>;
+  /** Optional annotations */
+  annotations?: Record<string, string>;
+}
+
+/** Base resource: apiVersion, kind, metadata, spec */
+export interface Resource<TKind extends string = string, TSpec = unknown> {
+  apiVersion: string;
+  kind: TKind;
+  metadata: ObjectMeta;
+  spec: TSpec;
+}
+
+// --- MemoryConfig (your example) ---
+
+export interface StoreSpec {
+  type: "in_memory" | string;
+  /** Backend-specific options (e.g. path for file store) */
+  options?: Record<string, unknown>;
+}
+
+export interface SessionCompactionSpec {
+  enabled: boolean;
+  maxTokens: number;
+  keepRecentTurns: number;
+  summaryKey: string;
+  checkEveryTurns: number;
+}
+
+export interface MemoryStoreSpec {
+  store: StoreSpec;
+  allowWrite: boolean;
+  maxItems: number;
+  sessionCompaction?: SessionCompactionSpec;
+}
+
+export interface MemorySpec {
+  thread: MemoryStoreSpec;
+  cross_thread: MemoryStoreSpec;
+  knowledge: MemoryStoreSpec;
+}
+
+export interface ObservabilitySpec {
+  trace: boolean;
+}
+
+export interface PrivacySpec {
+  forbiddenMetadataKeys: string[];
+}
+
+export interface MemoryConfigSpec {
+  memory: MemorySpec;
+  observability?: ObservabilitySpec;
+  privacy?: PrivacySpec;
+}
+
+export type MemoryConfigResource = Resource<"MemoryConfig", MemoryConfigSpec>;
+
+// --- SkillsConfig (for SKILL paths used by deepagents) ---
+
+export interface SkillsConfigSpec {
+  /** Optional cache directory for downloaded remote skills. */
+  cacheDir?: string;
+  /** Unified skill sources: local paths, GitHub Releases, or JFrog descriptors. */
+  skills: Record<string, Record<string, unknown>>;
+  /** Optional: which agent name this config applies to (for multi-agent setups) */
+  agent?: string;
+}
+
+export type SkillsConfigResource = Resource<"SkillsConfig", SkillsConfigSpec>;
+
+// --- AgentRuntimeConfig (runtime defaults consumed by AgentRuntimeService) ---
+
+export interface AgentBackendConfigSpec {
+  type?: "local_shell" | "deepagents_export" | "module_export";
+  exportName?: string;
+  module?: string;
+  createMethod?: string;
+  options?: Record<string, unknown>;
+  inheritEnv?: boolean;
+  timeoutMs?: number;
+  maxOutputBytes?: number;
+}
+
+export interface AgentRuntimeConfigSpec {
+  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";
+}
+
+export type AgentRuntimeConfigResource = Resource<"AgentRuntimeConfig", AgentRuntimeConfigSpec>;
+
+// --- Union of known kinds for type-safe loading ---
+
+export type KnownResource = MemoryConfigResource | SkillsConfigResource | AgentRuntimeConfigResource;
+
+export type KnownKind = KnownResource["kind"];
+
+/** Type guard: resource is MemoryConfig */
+export function isMemoryConfig(
+  r: Resource<string, unknown>
+): r is MemoryConfigResource {
+  return r.kind === "MemoryConfig";
+}
+
+/** Type guard: resource is SkillsConfig */
+export function isSkillsConfig(
+  r: Resource<string, unknown>
+): r is SkillsConfigResource {
+  return r.kind === "SkillsConfig";
+}
+
+/** Type guard: resource is AgentRuntimeConfig */
+export function isAgentRuntimeConfig(
+  r: Resource<string, unknown>
+): r is AgentRuntimeConfigResource {
+  return r.kind === "AgentRuntimeConfig";
+}

package/src/config/runtimeConfigLoader.ts

@@ -0,0 +1,68 @@
+/**
+ * High-level API for agent-runtime2 config loading: aggregate YAML resources into
+ * runtime, memory, observability, and privacy settings. Skill root resolution
+ * lives in @botbotgo/kit and is intentionally kept separate.
+ */
+
+import { loadFromFile, loadFromDirectory } from "./loader.js";
+import { resolveAgentConfig, type ResolvedAgentConfig } from "./resolveRuntimeConfig.js";
+import { type KnownResource } from "./resources.js";
+
+export interface LoadAgentRuntimeConfigOptions {
+  /** Load a single YAML config file */
+  configPath?: string;
+  /** Load all YAML resources from this directory */
+  configDir?: string;
+  /** Pre-loaded resources (skip file loading) */
+  resources?: KnownResource[];
+  /** If true, skip invalid documents when loading from directory (default: true) */
+  ignoreInvalid?: boolean;
+}
+
+export interface AgentRuntimeConfigResult {
+  resolved: ResolvedAgentConfig;
+}
+
+export class AgentRuntimeConfigService implements AgentRuntimeConfigResult {
+  public readonly resolved: ResolvedAgentConfig;
+
+  private constructor(resolved: ResolvedAgentConfig) {
+    this.resolved = resolved;
+  }
+
+  public static async create(
+    options: LoadAgentRuntimeConfigOptions,
+  ): Promise<AgentRuntimeConfigService> {
+    const resources = await AgentRuntimeConfigService.loadResources(options);
+    const resolved = resolveAgentConfig(resources);
+    return new AgentRuntimeConfigService(resolved);
+  }
+
+  private static async loadResources(options: LoadAgentRuntimeConfigOptions): Promise<KnownResource[]> {
+    if (options.resources) {
+      return options.resources;
+    }
+
+    if (options.configDir) {
+      const raw = await loadFromDirectory(options.configDir, {
+        ignoreInvalid: options.ignoreInvalid ?? true,
+      });
+      return raw as KnownResource[];
+    }
+
+    if (options.configPath) {
+      const single = await loadFromFile(options.configPath);
+      return [single as KnownResource];
+    }
+
+    throw new Error(
+      "loadAgentRuntimeConfig: provide one of configPath, configDir, or resources",
+    );
+  }
+}
+
+export async function loadAgentRuntimeConfig(
+  options: LoadAgentRuntimeConfigOptions,
+): Promise<AgentRuntimeConfigResult> {
+  return AgentRuntimeConfigService.create(options);
+}

package/src/external-modules.d.ts

@@ -0,0 +1,20 @@
+declare module "@botbotgo/kit" {
+  export function createAgentTools(...args: any[]): Promise<any>;
+  export function resolveAgentSkillRootsFromToolConfig(...args: any[]): string[];
+}
+
+declare module "@botbotgo/model" {
+  export function createAgentModel(...args: any[]): Promise<void>;
+}
+
+declare module "@botbotgo/memory" {
+  export function createAgentMemory(...args: any[]): Promise<any>;
+
+  export interface AgentMemoryStoreAdapterOptions {
+    agentMemory: any;
+  }
+
+  export class AgentMemoryStoreAdapter {
+    constructor(...args: any[]);
+  }
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+export {
+  AgentRuntimeService,
+  createAgentRuntime2,
+  initializeAgentRuntimeModules,
+} from "./runtime/index.js";
+export type { ResolvedAgentRuntimeConfig } from "./config/index.js";
+export type {
+  CreateAgentRuntimeFrameworkOptions,
+  HumanLoopDecision,
+  HumanLoopRequest,
+  HumanLoopService,
+  HumanLoopToolCallContext,
+  HumanLoopToolPolicy,
+} from "./runtime/index.js";
+export {
+  ConsoleHumanLoopService,
+  createDefaultHumanLoopToolPolicy,
+} from "./runtime/index.js";
+export { createRuntime2TreeEventListener } from "@botbotgo/common";
+export type {
+  Runtime2EventDebugConfig,
+  Runtime2EventRuntimeConfig,
+  Runtime2TreeEventListenerOptions,
+} from "@botbotgo/common";
+export {
+  clearAgentRuntimeGlobalContext,
+  getAgentRuntimeGlobal,
+  getAgentRuntimeGlobalContext,
+  getOrRegisterAgentRuntimeGlobal,
+  registerAgentRuntimeGlobal,
+  requireAgentRuntimeChatModel,
+  requireAgentRuntimeContextValue,
+  requireAgentRuntimeMemory,
+  requireAgentRuntimeTools,
+} from "./runtime/index.js";
+export type { AgentRuntimeGlobalContext } from "./runtime/index.js";

package/src/runtime/agentMiddleware.ts

@@ -0,0 +1,6 @@
+export { AgentToolMiddlewareFactory } from "./middleware/index.js";
+export type {
+  CreateAgentToolMiddlewareOptions,
+  ToolCallAfterHookContext,
+  ToolCallHookContext,
+} from "./middleware/index.js";

package/src/runtime/bootstrap/runtimeFactory.ts

@@ -0,0 +1,212 @@
+import { resolve } from "node:path";
+import { resolveAgentSkillRootsFromToolConfig } from "@botbotgo/kit";
+import { AgentToolMiddlewareFactory, type CreateAgentToolMiddlewareOptions } from "../middleware/index.js";
+import { ToolConfigReader } from "../execution/policies/toolConfigReader.js";
+import {
+  createAgentWorkspaceState,
+  type AgentWorkspaceState,
+  type CreateAgentWorkspaceStateOptions,
+} from "../../state/workspaceState.js";
+import {
+  OpenAILocalAgentService,
+  LangchainRuntimeBindingsResolver,
+  type AgentBackendConfig,
+} from "../providers/index.js";
+import { loadAgentRuntimeConfig } from "../../config/runtimeConfigLoader.js";
+import { AgentRuntimeEventPublisher, type AgentEventBus } from "../events/eventPublisher.js";
+import type { ResolvedAgentRuntimeConfig } from "../../config/index.js";
+import { AgentRuntimeService, type CreateAgentRuntimeOptions } from "../runtimeService.js";
+import { createDefaultHumanLoopToolPolicy } from "../human-loop/humanLoop.js";
+
+export class AgentRuntimeFactory {
+  public static async create(options: CreateAgentRuntimeOptions): Promise<AgentRuntimeService> {
+    const runtimeOptions = new RuntimeOptionsResolver(options);
+    const toolConfigPath = runtimeOptions.resolveToolConfigPath();
+    const { resolved } = await loadAgentRuntimeConfig({
+      configDir: runtimeOptions.configDir,
+      ignoreInvalid: true,
+    });
+    const skillRoots = resolveAgentSkillRootsFromToolConfig({ configFilePath: toolConfigPath });
+    const runtimeConfig = resolved.runtime;
+    const runtimeDeps = runtimeOptions.resolve(runtimeConfig);
+    const { createMiddleware, ToolMessage } = LangchainRuntimeBindingsResolver.resolve(runtimeOptions.rootDir);
+    const events = new AgentRuntimeEventPublisher(runtimeOptions.eventBus);
+    const workspace = this.createWorkspace(runtimeOptions.rootDir, runtimeDeps, events, runtimeOptions.todosLogger);
+    const middleware = this.createMiddleware(
+      runtimeOptions.rootDir,
+      skillRoots,
+      runtimeDeps,
+      events,
+      workspace,
+      createMiddleware,
+      ToolMessage,
+    );
+    const runtimeAgent = await OpenAILocalAgentService.create({
+      rootDir: runtimeOptions.rootDir,
+      configDir: runtimeOptions.configDir,
+      toolConfigPath: runtimeDeps.toolConfigPath,
+      allowedToolNames: runtimeDeps.allowedToolNames,
+      modelConfigPath: runtimeDeps.modelConfigPath,
+      modelCheckConnectivity: runtimeDeps.modelCheckConnectivity,
+      model: runtimeDeps.model,
+      systemPrompt: runtimeDeps.systemPrompt,
+      temperature: runtimeDeps.temperature,
+      maxTokens: runtimeDeps.maxTokens,
+      backend: runtimeDeps.backend,
+      middleware: [middleware],
+      logger: runtimeOptions.runLogger,
+    });
+
+    return new AgentRuntimeService({
+      rootDir: runtimeOptions.rootDir,
+      runLogger: runtimeOptions.runLogger,
+      events,
+      runtimeConfig,
+      middleware,
+      workspace,
+      runtimeAgent,
+      defaultIncompleteRunMaxRetries: runtimeDeps.defaultIncompleteRunMaxRetries,
+      defaultEmptyRunMaxRetries: runtimeDeps.defaultEmptyRunMaxRetries,
+      defaultMalformedToolCallMaxRetries: runtimeDeps.defaultMalformedToolCallMaxRetries,
+      defaultIdleTimeoutMaxRetries: runtimeDeps.defaultIdleTimeoutMaxRetries,
+      defaultHeartbeatIntervalMs: runtimeDeps.defaultHeartbeatIntervalMs,
+      defaultIdleTimeoutMs: runtimeDeps.defaultIdleTimeoutMs,
+      artifactValidator: runtimeDeps.artifactValidator,
+    });
+  }
+
+  private static createWorkspace(
+    rootDir: string,
+    runtimeDeps: ResolvedRuntimeOptions,
+    events: AgentRuntimeEventPublisher,
+    todosLogger: CreateAgentWorkspaceStateOptions["todosLogger"],
+  ): AgentWorkspaceState {
+    return createAgentWorkspaceState({
+      rootDir,
+      artifacts: runtimeDeps.artifacts,
+      stateDirName: runtimeDeps.stateDirName,
+      legacyOutputState: runtimeDeps.legacyOutputState,
+      todosLogger,
+      events,
+    });
+  }
+
+  private static createMiddleware(
+    rootDir: string,
+    skillRoots: string[],
+    runtimeDeps: ResolvedRuntimeOptions,
+    events: AgentRuntimeEventPublisher,
+    workspace: AgentWorkspaceState,
+    createMiddleware: CreateAgentToolMiddlewareOptions["createMiddleware"],
+    ToolMessage: CreateAgentToolMiddlewareOptions["ToolMessage"],
+  ): unknown {
+    return new AgentToolMiddlewareFactory({
+      rootDir,
+      skillRoots,
+      createMiddleware,
+      ToolMessage,
+      events,
+      executeTimeoutMs: runtimeDeps.executeTimeoutMs,
+      blockTaskTool: runtimeDeps.blockTaskTool,
+      allowedToolNames: runtimeDeps.allowedToolNames,
+      logger: runtimeDeps.logger,
+      persistTodos: workspace.persistTodos.bind(workspace),
+      humanLoop: runtimeDeps.humanLoop,
+      humanLoopToolPolicy: runtimeDeps.humanLoopToolPolicy,
+      beforeToolCall: runtimeDeps.beforeToolCall,
+      afterToolCall: runtimeDeps.afterToolCall,
+    }).create();
+  }
+}
+
+class RuntimeOptionsResolver {
+  public readonly rootDir: string;
+  public readonly configDir: string;
+  public readonly eventBus?: AgentEventBus;
+  public readonly todosLogger?: CreateAgentWorkspaceStateOptions["todosLogger"];
+  public readonly runLogger: (message: string) => void;
+
+  private readonly options: CreateAgentRuntimeOptions;
+
+  public constructor(options: CreateAgentRuntimeOptions) {
+    this.options = options;
+    this.rootDir = options.rootDir;
+    this.configDir = options.configDir ?? resolve(options.rootDir, "config");
+    this.eventBus = options.eventBus;
+    this.todosLogger = options.todosLogger;
+    this.runLogger = options.runLogger ?? (() => {});
+  }
+
+  public resolve(runtimeConfig: ResolvedAgentRuntimeConfig): ResolvedRuntimeOptions {
+    const toolConfigPath = this.resolveToolConfigPath();
+    return {
+      artifacts: this.options.artifacts ?? runtimeConfig.artifacts,
+      stateDirName: this.options.stateDirName ?? runtimeConfig.stateDirName,
+      legacyOutputState: this.options.legacyOutputState ?? runtimeConfig.legacyOutputState,
+      executeTimeoutMs: this.options.executeTimeoutMs ?? runtimeConfig.executeTimeoutMs,
+      blockTaskTool: this.options.blockTaskTool ?? runtimeConfig.blockTaskTool,
+      systemPrompt: this.options.systemPrompt ?? runtimeConfig.systemPrompt,
+      toolConfigPath,
+      allowedToolNames: ToolConfigReader.readAllowedToolNames(toolConfigPath),
+      modelConfigPath: this.options.modelConfigPath ?? resolve(this.configDir, "model.yaml"),
+      modelCheckConnectivity: this.options.modelCheckConnectivity ?? false,
+      model: this.options.model,
+      temperature: this.options.temperature,
+      maxTokens: this.options.maxTokens,
+      backend: this.options.backend ?? runtimeConfig.backend,
+      logger: this.options.logger,
+      humanLoop: this.options.humanLoop,
+      humanLoopToolPolicy: this.options.humanLoop
+        ? (this.options.humanLoopToolPolicy ?? createDefaultHumanLoopToolPolicy())
+        : this.options.humanLoopToolPolicy,
+      beforeToolCall: this.options.beforeToolCall,
+      afterToolCall: this.options.afterToolCall,
+      artifactValidator: this.options.artifactValidator,
+      defaultIncompleteRunMaxRetries:
+        this.options.incompleteRunMaxRetries ?? runtimeConfig.incompleteRunMaxRetries,
+      defaultEmptyRunMaxRetries:
+        this.options.emptyRunMaxRetries ?? runtimeConfig.emptyRunMaxRetries,
+      defaultMalformedToolCallMaxRetries:
+        this.options.malformedToolCallMaxRetries ?? runtimeConfig.malformedToolCallMaxRetries,
+      defaultIdleTimeoutMaxRetries:
+        this.options.idleTimeoutMaxRetries ?? runtimeConfig.idleTimeoutMaxRetries,
+      defaultHeartbeatIntervalMs:
+        this.options.heartbeatIntervalMs ?? runtimeConfig.heartbeatIntervalMs,
+      defaultIdleTimeoutMs:
+        this.options.idleTimeoutMs ?? runtimeConfig.llmIdleTimeoutMs,
+    };
+  }
+
+  public resolveToolConfigPath(): string {
+    return this.options.toolConfigPath ?? resolve(this.configDir, "tool.yaml");
+  }
+}
+
+interface ResolvedRuntimeOptions {
+  artifacts: CreateAgentRuntimeOptions["artifacts"];
+  stateDirName: CreateAgentRuntimeOptions["stateDirName"];
+  legacyOutputState: CreateAgentRuntimeOptions["legacyOutputState"];
+  executeTimeoutMs: number | undefined;
+  blockTaskTool: boolean | undefined;
+  systemPrompt: string | undefined;
+  toolConfigPath: string;
+  allowedToolNames: string[] | undefined;
+  modelConfigPath: string;
+  modelCheckConnectivity: boolean;
+  model: string | undefined;
+  temperature: number | undefined;
+  maxTokens: number | undefined;
+  backend: AgentBackendConfig | undefined;
+  logger: CreateAgentRuntimeOptions["logger"];
+  humanLoop: CreateAgentRuntimeOptions["humanLoop"];
+  humanLoopToolPolicy: CreateAgentRuntimeOptions["humanLoopToolPolicy"];
+  beforeToolCall: CreateAgentRuntimeOptions["beforeToolCall"];
+  afterToolCall: CreateAgentRuntimeOptions["afterToolCall"];
+  artifactValidator: CreateAgentRuntimeOptions["artifactValidator"];
+  defaultIncompleteRunMaxRetries: number | undefined;
+  defaultEmptyRunMaxRetries: number | undefined;
+  defaultMalformedToolCallMaxRetries: number | undefined;
+  defaultIdleTimeoutMaxRetries: number | undefined;
+  defaultHeartbeatIntervalMs: number | undefined;
+  defaultIdleTimeoutMs: number | undefined;
+}

package/src/runtime/bootstrap/runtimeModuleInitializer.ts

@@ -0,0 +1,34 @@
+import { resolve } from "node:path";
+import { AgentContextTokens, getDefaultAgentContext } from "@botbotgo/common/context";
+import { createAgentEventBus } from "@botbotgo/common/events";
+import { createAgentMemory } from "@botbotgo/memory";
+import { createAgentModel } from "@botbotgo/model";
+import { createAgentTools } from "@botbotgo/kit";
+import type { CreateAgentRuntimeFrameworkOptions } from "../runtimeService.js";
+
+export class AgentRuntimeModuleInitializer {
+  public static async initialize(options: CreateAgentRuntimeFrameworkOptions): Promise<void> {
+    const context = getDefaultAgentContext();
+    const configDir = options.configDir ?? resolve(options.rootDir, "config");
+    const modelConfigPath = options.modelConfigPath ?? resolve(configDir, "model.yaml");
+    const memoryConfigPath = options.memoryConfigPath ?? resolve(configDir, "memory.yaml");
+    const toolConfigPath = options.toolConfigPath ?? resolve(configDir, "tool.yaml");
+    const forceInitializeModules = options.forceInitializeModules ?? false;
+
+    if (forceInitializeModules || !context.has(AgentContextTokens.EventBus)) {
+      createAgentEventBus();
+    }
+    if (forceInitializeModules || !context.has(AgentContextTokens.ChatModel)) {
+      await createAgentModel({
+        configPath: modelConfigPath,
+        checkConnectivity: options.modelCheckConnectivity ?? false,
+      });
+    }
+    if (forceInitializeModules || !context.has(AgentContextTokens.Memory)) {
+      await createAgentMemory(memoryConfigPath);
+    }
+    if (forceInitializeModules || !context.has(AgentContextTokens.Tools)) {
+      await createAgentTools(toolConfigPath);
+    }
+  }
+}

package/src/runtime/context/agentContext.ts

@@ -0,0 +1,24 @@
+import { AgentContextTokens, getDefaultAgentContext } from "@botbotgo/common/context";
+
+export function requireAgentRuntimeContextValue<T>(token: symbol, label: string): T {
+  const context = getDefaultAgentContext();
+  const value = context.tryGet<T>(token);
+  if (value === undefined) {
+    throw new Error(
+      `agent-runtime2 requires ${label} to be registered in AgentContext before runtime creation.`,
+    );
+  }
+  return value;
+}
+
+export function requireAgentRuntimeChatModel<T>(): T {
+  return requireAgentRuntimeContextValue<T>(AgentContextTokens.ChatModel, "ChatModel");
+}
+
+export function requireAgentRuntimeMemory<T>(): T {
+  return requireAgentRuntimeContextValue<T>(AgentContextTokens.Memory, "Memory");
+}
+
+export function requireAgentRuntimeTools<T>(): T {
+  return requireAgentRuntimeContextValue<T>(AgentContextTokens.Tools, "Tools");
+}

package/src/runtime/context/globalContext.ts

@@ -0,0 +1,70 @@
+const AGENT_RUNTIME2_GLOBAL_CONTEXT_KEY = "__agent_runtime2_global_context__";
+
+export interface AgentRuntimeGlobalContext {
+  register<T>(key: PropertyKey, value: T): T;
+  get<T>(key: PropertyKey): T | undefined;
+  getOrRegister<T>(key: PropertyKey, create: () => T): T;
+  has(key: PropertyKey): boolean;
+  remove(key: PropertyKey): boolean;
+  clear(): void;
+}
+
+type GlobalContextStore = Map<PropertyKey, unknown>;
+
+declare global {
+  var __agent_runtime2_global_context__: GlobalContextStore | undefined;
+}
+
+function getStore(): GlobalContextStore {
+  globalThis[AGENT_RUNTIME2_GLOBAL_CONTEXT_KEY] ??= new Map<PropertyKey, unknown>();
+  return globalThis[AGENT_RUNTIME2_GLOBAL_CONTEXT_KEY];
+}
+
+export function getAgentRuntimeGlobalContext(): AgentRuntimeGlobalContext {
+  const store = getStore();
+  return {
+    register<T>(key: PropertyKey, value: T): T {
+      store.set(key, value);
+      return value;
+    },
+    get<T>(key: PropertyKey): T | undefined {
+      return store.get(key) as T | undefined;
+    },
+    getOrRegister<T>(key: PropertyKey, create: () => T): T {
+      if (store.has(key)) {
+        return store.get(key) as T;
+      }
+      const value = create();
+      store.set(key, value);
+      return value;
+    },
+    has(key: PropertyKey): boolean {
+      return store.has(key);
+    },
+    remove(key: PropertyKey): boolean {
+      return store.delete(key);
+    },
+    clear(): void {
+      store.clear();
+    },
+  };
+}
+
+export function registerAgentRuntimeGlobal<T>(key: PropertyKey, value: T): T {
+  return getAgentRuntimeGlobalContext().register(key, value);
+}
+
+export function getAgentRuntimeGlobal<T>(key: PropertyKey): T | undefined {
+  return getAgentRuntimeGlobalContext().get<T>(key);
+}
+
+export function getOrRegisterAgentRuntimeGlobal<T>(
+  key: PropertyKey,
+  create: () => T,
+): T {
+  return getAgentRuntimeGlobalContext().getOrRegister(key, create);
+}
+
+export function clearAgentRuntimeGlobalContext(): void {
+  getAgentRuntimeGlobalContext().clear();
+}

package/src/runtime/events/eventPublisher.ts

@@ -0,0 +1,45 @@
+import {
+  AgentContextTokens,
+  getDefaultAgentContext,
+  createAgentEventBus,
+  type AgentEvent,
+  type AgentEventBus,
+  type AgentEventListener,
+} from "@botbotgo/common";
+
+export type { AgentEvent, AgentEventBus, AgentEventListener };
+
+export interface RuntimeEventEnvelope<TPayload = unknown> {
+  name: string;
+  from?: string;
+  to?: string;
+  payload?: TPayload;
+}
+
+function getRuntime2EventBus(): AgentEventBus {
+  return (
+    getDefaultAgentContext().tryGet<AgentEventBus>(AgentContextTokens.EventBus)
+    ?? createAgentEventBus()
+  );
+}
+
+export class AgentRuntimeEventPublisher {
+  public readonly bus: AgentEventBus;
+
+  public constructor(bus?: AgentEventBus) {
+    this.bus = bus ?? getRuntime2EventBus();
+  }
+
+  public emit<TPayload = unknown>(event: RuntimeEventEnvelope<TPayload>): AgentEvent<TPayload> {
+    return this.bus.publish({
+      name: event.name,
+      from: event.from ?? "agent-runtime2",
+      to: event.to ?? "agent-runtime2",
+      payload: event.payload,
+    });
+  }
+
+  public subscribe(listener: AgentEventListener): () => void {
+    return this.bus.subscribe(listener);
+  }
+}