openbot 0.2.14 → 0.3.1

package/src/bus/types.ts

@@ -0,0 +1,160 @@
+import type { OpenBotEvent } from '../app/types.js';
+import type { PluginRef } from './plugin.js';
+import type { MemoryRecord, ListMemoriesArgs } from '../services/memory.js';
+
+/**
+ * Public data types exposed by the OpenBot bus.
+ *
+ * The bus is the platform layer that owns channels, threads, the agent registry,
+ * and the event stream. Agents are composed entirely of Plugins (see
+ * `bus/plugin.ts`); their internal implementation is opaque to the bus.
+ */
+
+export type Agent = {
+  id: string;
+  name: string;
+  description: string;
+  image?: string;
+  /** Plugin ids that compose this agent (mirrors AGENT.md `plugins[].id`). */
+  plugins: string[];
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+export type AgentDetails = Agent & {
+  instructions: string;
+  /** Full plugin refs from AGENT.md (with per-plugin config). */
+  pluginRefs: PluginRef[];
+};
+
+export type PluginDescriptor = {
+  id: string;
+  name: string;
+  description: string;
+  /** True when bundled with the core server (`src/registry/plugins`); false for ~/.openbot/plugins installs. */
+  builtIn: boolean;
+  image?: string;
+  defaultInstructions?: string;
+  configSchema?: ConfigSchema;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+export type ConfigSchema = {
+  type: 'object';
+  properties: {
+    [key: string]: {
+      type: 'string' | 'number' | 'boolean' | 'integer';
+      description?: string;
+      default?: unknown;
+      enum?: unknown[];
+      minimum?: number;
+      maximum?: number;
+      format?: 'password' | 'url' | 'email';
+    };
+  };
+  required?: string[];
+};
+
+export type Channel = {
+  id: string;
+  name: string;
+  description: string;
+  cwd?: string;
+  createdAt: Date;
+  updatedAt: Date;
+  hasUnseenMessages?: boolean;
+  recentThreads?: Thread[];
+};
+
+export type Thread = {
+  id: string;
+  name: string;
+  channelId: string;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+export type ThreadDetails = {
+  id: string;
+  name: string;
+  channelId: string;
+  spec: string;
+  state: unknown;
+};
+
+export type ChannelDetails = {
+  id: string;
+  name: string;
+  spec: string;
+  state: unknown;
+  cwd?: string;
+  threads?: Thread[];
+};
+
+export interface Storage {
+  getChannels: () => Promise<Channel[]>;
+  createChannel: (args: {
+    channelId: string;
+    spec?: string;
+    initialState?: Record<string, unknown>;
+    cwd?: string;
+  }) => Promise<void>;
+  createThread: (args: {
+    channelId: string;
+    threadId: string;
+    threadTitle?: string;
+    spec?: string;
+    initialState?: Record<string, unknown>;
+  }) => Promise<void>;
+  getThreads: (args: { channelId: string }) => Promise<Thread[]>;
+  getThreadDetails: (args: { channelId: string; threadId: string }) => Promise<ThreadDetails>;
+  getAgents: () => Promise<Agent[]>;
+  getPlugins: () => Promise<PluginDescriptor[]>;
+  getAgentDetails: (args: { agentId: string }) => Promise<AgentDetails>;
+  createAgent: (args: {
+    agentId: string;
+    name: string;
+    description?: string;
+    instructions: string;
+    plugins: PluginRef[];
+  }) => Promise<void>;
+  updateAgent: (args: {
+    agentId: string;
+    name?: string;
+    description?: string;
+    instructions?: string;
+    plugins?: PluginRef[];
+  }) => Promise<void>;
+  deleteAgent: (args: { agentId: string }) => Promise<void>;
+  getEvents: (args: { channelId: string; threadId?: string }) => Promise<OpenBotEvent[]>;
+  getChannelDetails: (args: { channelId: string }) => Promise<ChannelDetails>;
+  patchChannelState: (args: { channelId: string; state: unknown }) => Promise<void>;
+  patchThreadState: (args: {
+    channelId: string;
+    threadId: string;
+    state: unknown;
+  }) => Promise<void>;
+  patchChannelSpec: (args: { channelId: string; spec: string }) => Promise<void>;
+  patchThreadSpec: (args: { channelId: string; threadId: string; spec: string }) => Promise<void>;
+  getVariables: () => Promise<Record<string, string | { value: string; secret: boolean }>>;
+  createVariable: (args: { key: string; value: string; secret?: boolean }) => Promise<void>;
+  deleteVariable: (args: { key: string }) => Promise<void>;
+  listFiles: (args: {
+    channelId: string;
+    path?: string;
+  }) => Promise<Array<{ name: string; isDirectory: boolean }>>;
+  readFile: (args: { channelId: string; path: string }) => Promise<string>;
+  /** Persist a memory record into the global memory log. */
+  appendMemory: (args: {
+    scope: string;
+    content: string;
+    tags?: string[];
+  }) => Promise<MemoryRecord>;
+  /** Read memories matching the given filter. */
+  listMemories: (args?: ListMemoriesArgs) => Promise<MemoryRecord[]>;
+  /** Soft-delete a memory by id. Returns true if a record was deleted. */
+  deleteMemory: (args: { id: string }) => Promise<boolean>;
+  /** Update a memory's content/tags by id. Returns true if a record was updated. */
+  updateMemory: (args: { id: string; content?: string; tags?: string[] }) => Promise<boolean>;
+}

package/src/harness/context.ts

@@ -0,0 +1,293 @@
+import { OpenBotEvent, OpenBotState } from '../app/types.js';
+import { Storage } from '../bus/types.js';
+
+/**
+ * Represents a piece of context that can be used in a prompt.
+ *
+ * Items flow through the engine in two phases:
+ *   1. Each registered `ContextProvider` emits zero or more items.
+ *   2. Each registered `ContextProcessor` may transform / drop / re-rank
+ *      items (e.g. token-budget enforcement).
+ *
+ * Higher `priority` items appear first in the assembled prompt and are the
+ * last to be dropped under budget pressure.
+ */
+export interface ContextItem {
+  id: string;
+  type: string;
+  priority: number;
+  content: string;
+  metadata?: Record<string, any>;
+}
+
+export interface ContextProvider {
+  name: string;
+  provide(state: OpenBotState, storage?: Storage): Promise<ContextItem[]>;
+}
+
+export interface ContextProcessor {
+  name: string;
+  process(items: ContextItem[], state: OpenBotState): Promise<ContextItem[]>;
+}
+
+/**
+ * Cheap, dependency-free token estimator. Roughly char/4 — fine for budget
+ * enforcement; can be swapped for a tokenizer-backed implementation later
+ * without touching providers.
+ */
+export const estimateTokens = (text: string): number =>
+  Math.ceil((text?.length ?? 0) / 4);
+
+/**
+ * Hard cap (in characters) on a single context item. Keeps any one provider
+ * — typically the recent-events feed — from monopolising the prompt budget.
+ */
+const ITEM_HARD_CHAR_CAP = 6000;
+
+const truncate = (text: string, maxChars: number): string =>
+  text.length <= maxChars ? text : `${text.slice(0, maxChars)}\n…[truncated]`;
+
+export class ContextEngine {
+  private providers: ContextProvider[] = [];
+  private processors: ContextProcessor[] = [];
+
+  registerProvider(provider: ContextProvider) {
+    this.providers.push(provider);
+  }
+
+  registerProcessor(processor: ContextProcessor) {
+    this.processors.push(processor);
+  }
+
+  async buildContext(state: OpenBotState, storage?: Storage): Promise<string> {
+    let items: ContextItem[] = [];
+    for (const provider of this.providers) {
+      try {
+        const providedItems = await provider.provide(state, storage);
+        for (const item of providedItems) {
+          items.push({ ...item, content: truncate(item.content, ITEM_HARD_CHAR_CAP) });
+        }
+      } catch (error) {
+        console.warn(`[ContextEngine] Provider ${provider.name} failed:`, error);
+      }
+    }
+
+    for (const processor of this.processors) {
+      try {
+        items = await processor.process(items, state);
+      } catch (error) {
+        console.warn(`[ContextEngine] Processor ${processor.name} failed:`, error);
+      }
+    }
+
+    return items
+      .sort((a, b) => b.priority - a.priority)
+      .map((item) => item.content)
+      .join('\n\n');
+  }
+}
+
+/**
+ * Default context engine. Order of providers is by emit order; final ordering
+ * in the prompt is determined by `priority`. The token-budget processor runs
+ * last so dropping happens after every provider has contributed.
+ */
+export function createDefaultContextEngine(): ContextEngine {
+  const engine = new ContextEngine();
+
+  engine.registerProvider(new AgentDetailsProvider());
+  engine.registerProvider(new ChannelDetailsProvider());
+  engine.registerProvider(new ThreadDetailsProvider());
+  engine.registerProvider(new MemoryProvider());
+  engine.registerProvider(new RecentEventsProvider());
+
+  engine.registerProcessor(new TokenBudgetProcessor());
+
+  return engine;
+}
+
+class AgentDetailsProvider implements ContextProvider {
+  name = 'agent-details';
+  async provide(state: OpenBotState): Promise<ContextItem[]> {
+    if (!state.agentDetails) return [];
+    return [{
+      id: 'agent-details',
+      type: 'agent',
+      priority: 100,
+      content: `## AGENT NAME\n${state.agentDetails.name}\n\n## AGENT SPECIFICATION\n${state.agentDetails.instructions}`
+    }];
+  }
+}
+
+class ChannelDetailsProvider implements ContextProvider {
+  name = 'channel-details';
+  async provide(state: OpenBotState): Promise<ContextItem[]> {
+    if (!state.channelDetails) return [];
+    return [{
+      id: 'channel-details',
+      type: 'channel',
+      priority: 80,
+      content: `## CHANNEL NAME\n${state.channelDetails.name}\n\n## CHANNEL SPECIFICATION\n${state.channelDetails.spec}`
+    }];
+  }
+}
+
+class ThreadDetailsProvider implements ContextProvider {
+  name = 'thread-details';
+  async provide(state: OpenBotState): Promise<ContextItem[]> {
+    if (!state.threadDetails) return [];
+    return [{
+      id: 'thread-details',
+      type: 'thread',
+      priority: 90,
+      content: `## THREAD NAME\n${state.threadDetails.name}\n\n## THREAD SPECIFICATION\n${state.threadDetails.spec}`
+    }];
+  }
+}
+
+/**
+ * Fetches relevant memories (global + active agent + active channel) and
+ * surfaces them at high priority so the LLM treats them as ground truth
+ * rather than chat history.
+ */
+class MemoryProvider implements ContextProvider {
+  name = 'memory';
+  async provide(state: OpenBotState, storage?: Storage): Promise<ContextItem[]> {
+    if (!storage?.listMemories) return [];
+
+    try {
+      const scopes = ['global', `agent:${state.agentId}`];
+      if (state.channelId) scopes.push(`channel:${state.channelId}`);
+
+      const records = await storage.listMemories({ scopes, limit: 50 });
+      if (records.length === 0) return [];
+
+      const formatted = records
+        .map((r) => {
+          const tags = r.tags?.length ? ` [${r.tags.join(', ')}]` : '';
+          const scopeLabel = r.scope === 'global' ? 'global' : r.scope;
+          return `- (${scopeLabel}${tags}) ${r.content}`;
+        })
+        .join('\n');
+
+      return [
+        {
+          id: 'memory',
+          type: 'memory',
+          priority: 95,
+          content: `## REMEMBERED FACTS\nThese are durable facts you previously stored with the \`remember\` tool. Trust them unless contradicted by the user. Use \`forget\` to remove ones that are stale.\n\n${formatted}`,
+        },
+      ];
+    } catch (error) {
+      console.warn('[ContextEngine] MemoryProvider failed:', error);
+      return [];
+    }
+  }
+}
+
+/**
+ * Event types we omit from the recent-events context block. They duplicate
+ * information already in the conversation history, are infrastructural
+ * noise, or are too large to be useful as a tail summary.
+ */
+const NOISY_EVENT_PREFIXES = [
+  'agent:invoke',
+  'agent:output',
+  'agent:run',
+  'agent:active-runs',
+  'client:ui',
+  'stream:',
+  'action:storage:get-',
+  'action:storage:patch-',
+];
+
+const MAX_RECENT_EVENTS = 20;
+const MAX_EVENT_DATA_CHARS = 300;
+
+const isNoisyEvent = (event: OpenBotEvent): boolean =>
+  NOISY_EVENT_PREFIXES.some((prefix) => event.type.startsWith(prefix));
+
+const summarizeEvent = (event: OpenBotEvent): string => {
+  const data = (event as { data?: unknown }).data;
+  if (data === undefined) return `- ${event.type}`;
+  let payload: string;
+  try {
+    payload = typeof data === 'string' ? data : JSON.stringify(data);
+  } catch {
+    payload = '[unserialisable]';
+  }
+  if (payload.length > MAX_EVENT_DATA_CHARS) {
+    payload = `${payload.slice(0, MAX_EVENT_DATA_CHARS)}…`;
+  }
+  return `- ${event.type}: ${payload}`;
+};
+
+class RecentEventsProvider implements ContextProvider {
+  name = 'recent-events';
+  async provide(state: OpenBotState, storage?: Storage): Promise<ContextItem[]> {
+    if (!storage) return [];
+
+    const channelId = state.channelId;
+    const threadId = state.threadId;
+
+    try {
+      const events = await storage.getEvents({ channelId, threadId });
+      const filtered = events.filter((e) => !isNoisyEvent(e));
+      if (filtered.length === 0) return [];
+
+      const formatted = filtered.slice(-MAX_RECENT_EVENTS).map(summarizeEvent).join('\n');
+
+      return [
+        {
+          id: threadId ? 'thread-events' : 'channel-events',
+          type: 'events',
+          priority: 70,
+          content: `## ${threadId ? 'THREAD' : 'CHANNEL'} RECENT ACTIVITIES (events)\n${formatted}`,
+        },
+      ];
+    } catch (error) {
+      console.warn('[ContextEngine] Failed to fetch events:', error);
+      return [];
+    }
+  }
+}
+
+/**
+ * Drops the lowest-priority items until the assembled prompt fits within the
+ * token budget. The first item with priority >= `keepFloor` is always kept,
+ * so the agent's own instructions can never be evicted. Stable on ties:
+ * later-emitted items go first.
+ */
+export class TokenBudgetProcessor implements ContextProcessor {
+  name = 'token-budget';
+  /** Soft prompt budget in tokens (matches gpt-4o-mini's reasonable system slice). */
+  static DEFAULT_BUDGET = 8000;
+  /** Items at or above this priority are never dropped. */
+  static KEEP_FLOOR = 100;
+
+  constructor(
+    private budget: number = TokenBudgetProcessor.DEFAULT_BUDGET,
+    private keepFloor: number = TokenBudgetProcessor.KEEP_FLOOR,
+  ) {}
+
+  async process(items: ContextItem[]): Promise<ContextItem[]> {
+    const sorted = [...items].sort((a, b) => b.priority - a.priority);
+    const out: ContextItem[] = [];
+    let used = 0;
+
+    for (const item of sorted) {
+      const cost = estimateTokens(item.content);
+      if (item.priority >= this.keepFloor) {
+        out.push(item);
+        used += cost;
+        continue;
+      }
+      if (used + cost <= this.budget) {
+        out.push(item);
+        used += cost;
+      }
+    }
+
+    return out;
+  }
+}

package/src/harness/event-normalizer.ts

@@ -0,0 +1,82 @@
+import { AgentInvokeEvent, OpenBotEvent, OpenBotState } from '../app/types.js';
+import { ensureEventId } from '../app/utils.js';
+import { storageService } from '../services/storage.js';
+
+export interface NormalizedEventResult {
+  finalEvent: OpenBotEvent;
+  finalAgentId: string;
+}
+
+export const EventNormalizer = {
+  /**
+   * Normalizes incoming events, converting raw inputs like user:input to agent:invoke.
+   * Also handles initial state storage and event bus propagation for user inputs.
+   */
+  normalize: async (
+    event: OpenBotEvent,
+    options: {
+      runId: string;
+      agentId?: string;
+      channelId: string;
+      threadId?: string;
+      onEvent: (chunk: OpenBotEvent, state: OpenBotState) => Promise<boolean | void>;
+    }
+  ): Promise<NormalizedEventResult> => {
+    const { runId, agentId, channelId, threadId, onEvent } = options;
+
+    // 0. Ensure the incoming event has a unique ID immediately
+    ensureEventId(event);
+
+    let finalAgentId = agentId || 'system';
+    let finalEvent = event;
+
+    // 1. Convert user:input (or other raw inputs) to agent:invoke
+    const rawContent = (event as any).data?.content || '';
+    if (event.type === 'user:input' || event.type === 'agent:invoke') {
+      const normalizedInvokeEvent: AgentInvokeEvent = {
+        type: 'agent:invoke',
+        id: event.id,
+        data: {
+          content: rawContent,
+          role: 'user',
+        },
+        meta: {
+          agentId: 'system',
+          userId: event.meta?.userId,
+          userName: event.meta?.userName,
+          userAvatarUrl: event.meta?.userAvatarUrl,
+        },
+      };
+      finalEvent = normalizedInvokeEvent;
+
+      // 1. Store the user's input in the current context (main channel or existing thread)
+      const initialState = await storageService.getOpenBotState({
+        runId,
+        agentId: 'system',
+        channelId,
+        threadId: threadId,
+        event: finalEvent,
+      });
+
+      // 2. Propagate the user's input to the event bus
+      await onEvent(finalEvent, initialState);
+
+      // 3. Prepare the event for the target agent
+      finalEvent = {
+        ...event,
+        type: 'agent:invoke',
+        data: {
+          ...((event as any).data || {}),
+          content: rawContent,
+        },
+        meta: {
+          ...(event.meta || {}),
+          // The threadId in meta is the anchor for new threads (Slack-style)
+          threadId: threadId || finalEvent.id,
+        },
+      };
+    }
+
+    return { finalEvent, finalAgentId };
+  },
+};