openbot 0.3.0 → 0.3.2

package/src/harness/context.ts

@@ -1,8 +1,16 @@
-import { OpenBotState } from '../app/types.js';
+import { OpenBotEvent, OpenBotState, TodoItem } 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;
@@ -12,25 +20,33 @@ export interface ContextItem {
   metadata?: Record<string, any>;
 }
 
-/**
- * A provider that can fetch or generate context items.
- */
 export interface ContextProvider {
   name: string;
   provide(state: OpenBotState, storage?: Storage): Promise<ContextItem[]>;
 }
 
-/**
- * A processor that can transform or filter context items (e.g., ranking, truncation).
- */
 export interface ContextProcessor {
   name: string;
   process(items: ContextItem[], state: OpenBotState): Promise<ContextItem[]>;
 }
 
 /**
- * The core engine that orchestrates context building.
+ * 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[] = [];
@@ -44,18 +60,18 @@ export class ContextEngine {
   }
 
   async buildContext(state: OpenBotState, storage?: Storage): Promise<string> {
-    // 1. Collect context from all providers
     let items: ContextItem[] = [];
     for (const provider of this.providers) {
       try {
         const providedItems = await provider.provide(state, storage);
-        items.push(...providedItems);
+        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);
       }
     }
 
-    // 2. Run through processors
     for (const processor of this.processors) {
       try {
         items = await processor.process(items, state);
@@ -64,26 +80,30 @@ export class ContextEngine {
       }
     }
 
-    // 3. Format items into a single string
     return items
       .sort((a, b) => b.priority - a.priority)
-      .map(item => item.content)
+      .map((item) => item.content)
       .join('\n\n');
   }
 }
 
 /**
- * Default implementation of a Context Engine with basic providers.
+ * 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();
 
-  // Basic Providers
   engine.registerProvider(new AgentDetailsProvider());
   engine.registerProvider(new ChannelDetailsProvider());
   engine.registerProvider(new ThreadDetailsProvider());
+  engine.registerProvider(new TodoProvider());
+  engine.registerProvider(new MemoryProvider());
   engine.registerProvider(new RecentEventsProvider());
 
+  engine.registerProcessor(new TokenBudgetProcessor());
+
   return engine;
 }
 
@@ -91,11 +111,14 @@ class AgentDetailsProvider implements ContextProvider {
   name = 'agent-details';
   async provide(state: OpenBotState): Promise<ContextItem[]> {
     if (!state.agentDetails) return [];
+    const instructions = state.agentDetails.instructions?.trim();
+    if (!instructions) return [];
+
     return [{
       id: 'agent-details',
       type: 'agent',
       priority: 100,
-      content: `## AGENT NAME\n${state.agentDetails.name}\n\n## AGENT SPECIFICATION\n${state.agentDetails.instructions}`
+      content: `# ${state.agentDetails.name}\n\n${instructions}`,
     }];
   }
 }
@@ -104,11 +127,14 @@ class ChannelDetailsProvider implements ContextProvider {
   name = 'channel-details';
   async provide(state: OpenBotState): Promise<ContextItem[]> {
     if (!state.channelDetails) return [];
+    const spec = state.channelDetails.spec?.trim();
+    if (!spec) return [];
+
     return [{
       id: 'channel-details',
       type: 'channel',
       priority: 80,
-      content: `## CHANNEL NAME\n${state.channelDetails.name}\n\n## CHANNEL SPECIFICATION\n${state.channelDetails.spec}`
+      content: `# Channel you are in: ${state.channelDetails.name}\n\n Channel Specification: ${spec}`,
     }];
   }
 }
@@ -117,44 +143,214 @@ 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}`
-    }];
+
+    // For now, this provider is a placeholder for future state-based assembly.
+    // It currently only surfaces the thread name to provide basic context.
+    return [
+      {
+        id: 'thread-details',
+        type: 'thread',
+        priority: 90,
+        content: `# Thread you are in: ${state.threadDetails.name}`,
+      },
+    ];
   }
 }
 
+/**
+ * Surfaces the shared per-thread todo list. The list lives in
+ * `threadDetails.state.todos` and is owned by bus services — every agent in
+ * the thread reads from the same canonical source, which is how multi-agent
+ * autonomous flows stay coordinated.
+ */
+class TodoProvider implements ContextProvider {
+  name = 'todos';
+  async provide(state: OpenBotState): Promise<ContextItem[]> {
+    const raw = (state.threadDetails?.state as Record<string, unknown> | undefined)?.todos;
+    const todos: TodoItem[] = Array.isArray(raw) ? (raw as TodoItem[]) : [];
+    if (todos.length === 0) return [];
+
+    const DISPLAY_RESULT_CAP = 2500;
+
+    const marker: Record<TodoItem['status'], string> = {
+      pending: '[ ]',
+      in_progress: '[~]',
+      done: '[x]',
+      cancelled: '[-]',
+    };
+    const formatted = todos
+      .map((t) => {
+        const assignee = t.assignee ? ` @${t.assignee}` : '';
+        let line = `- ${marker[t.status]} (${t.id})${assignee} ${t.content}`;
+        if (t.status === 'done' && t.result?.trim()) {
+          let snippet = t.result.trim();
+          if (snippet.length > DISPLAY_RESULT_CAP) {
+            snippet = `${snippet.slice(0, DISPLAY_RESULT_CAP)}…[truncated]`;
+          }
+          line += `\n  Result: ${snippet}`;
+        }
+        return line;
+      })
+      .join('\n');
+
+    return [
+      {
+        id: 'todos',
+        type: 'todos',
+        priority: 92,
+        content:
+          `## Shared todo plan (thread state)\n` +
+          `Orchestrator authors with \`todo_write\`; assignees run one step at a time. ` +
+          `When an item is \`done\`, its captured output appears below so every agent can see prior steps without relying on merged chat history.\n\n` +
+          `${formatted}`,
+      },
+    ];
+  }
+}
+
+/**
+ * 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\nTrust these unless the user contradicts them. Use \`forget\` to remove stale ones.\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 items: ContextItem[] = [];
 
-    // Fetch channel events if no thread, otherwise fetch thread events
     const channelId = state.channelId;
     const threadId = state.threadId;
 
     try {
       const events = await storage.getEvents({ channelId, threadId });
-      if (events.length > 0) {
-        const formattedEvents = events
-          .slice(-20)
-          .map((e) => `- ${e.type}: ${JSON.stringify((e as any).data || {})}`)
-          .join('\n');
-        
-        items.push({
+      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${formattedEvents}`
-        });
-      }
+          content: `## ${threadId ? 'THREAD' : 'CHANNEL'} RECENT ACTIVITIES (events)\n${formatted}`,
+        },
+      ];
     } catch (error) {
-      console.warn(`[ContextEngine] Failed to fetch events:`, 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 items;
+    return out;
   }
 }

package/src/harness/queue-processor.ts

@@ -1,22 +1,16 @@
 import {
   AgentInvokeEvent,
-  DelegateResultEvent,
-  DelegationRequestEvent,
   HandoffRequestEvent,
   OpenBotEvent,
   OpenBotState,
 } from '../app/types.js';
 import { ensureEventId } from '../app/utils.js';
 import { storageService } from '../services/storage.js';
+import { advanceAfterRun } from './todo-advance.js';
 
 export interface QueueItem {
   agentId: string;
   event: OpenBotEvent;
-  delegationContext?: {
-    parentAgentId: string;
-    toolCallId: string;
-    delegationWidgetId?: string;
-  };
 }
 
 export interface QueueProcessorOptions {
@@ -68,12 +62,12 @@ export class QueueProcessor {
         Array.from(groups.entries()).map(async ([agentId, items]) => {
           // Run items for the SAME agent sequentially to preserve event order and state consistency.
           for (const item of items) {
-            const { event: currentEvent, delegationContext } = item;
+            const { event: currentEvent } = item;
 
-            // Track delegation/handoff requests queued in this step to avoid accidental duplicates.
+            // Track handoff requests queued in this step to avoid accidental duplicates.
             const queuedRequestKeys = new Set<string>();
             const queuedItems: QueueItem[] = [];
-            const runOutputs: string[] = [];
+            let lastAgentOutput: string | undefined;
 
             const runOnEvent = async (chunk: OpenBotEvent, state: OpenBotState) => {
               // 0. Filter out echoed input events to prevent duplication in the UI/storage
@@ -81,26 +75,27 @@ export class QueueProcessor {
                 return false;
               }
 
+              if (chunk.type === 'agent:output') {
+                const outMeta = chunk.meta as { agentId?: string } | undefined;
+                if (outMeta?.agentId === agentId) {
+                  const content = chunk.data?.content;
+                  if (typeof content === 'string' && content.trim()) {
+                    lastAgentOutput = content.trim();
+                  }
+                }
+              }
+
               // 1. Detect if a new thread was created and update the context for the rest of the loop
               if (chunk.type === 'action:create_thread:result' && chunk.data.success) {
                 this.currentThreadId = chunk.data.threadId || this.currentThreadId;
               }
 
-              // 2. Internal routing (handoff/delegation requests are internal — not forwarded)
-              if (chunk.type === 'handoff:request' || chunk.type === 'delegation:request') {
-                const isHandoff = chunk.type === 'handoff:request';
-                const request = isHandoff
-                  ? (chunk as HandoffRequestEvent)
-                  : (chunk as DelegationRequestEvent);
+              // 2. Internal routing (handoff requests are internal — not forwarded)
+              if (chunk.type === 'handoff:request') {
+                const request = chunk as HandoffRequestEvent;
                 const targetAgentId = request.data?.agentId;
-                const toolCallId =
-                  typeof request.meta?.toolCallId === 'string'
-                    ? request.meta.toolCallId
-                    : undefined;
-                const requestKey = isHandoff
-                  ? `handoff:${targetAgentId}:${request.data?.content ?? ''}`
-                  : `delegate:${toolCallId ?? 'missing'}:${targetAgentId}:${request.data?.content ?? ''}`;
-                
+                const requestKey = `handoff:${targetAgentId}`;
+
                 if (
                   targetAgentId &&
                   targetAgentId !== agentId &&
@@ -119,62 +114,11 @@ export class QueueProcessor {
                     },
                   } satisfies AgentInvokeEvent) as AgentInvokeEvent;
 
-                  if (isHandoff) {
-                    queuedItems.push({ agentId: targetAgentId, event: targetEvent });
-                  } else {
-                    if (!toolCallId) {
-                      // Emit error output (this triggers run start if not already started)
-                      await runOnEvent(
-                        ensureEventId({
-                          type: 'agent:output',
-                          data: {
-                            content:
-                              'Delegation request ignored: missing toolCallId. Please retry delegation.',
-                          },
-                          meta: {
-                            agentId,
-                            threadId: this.currentThreadId,
-                          },
-                        } as OpenBotEvent),
-                        state,
-                      );
-                      return true;
-                    }
-                    const parentAgentId =
-                      typeof request.meta?.parentAgentId === 'string'
-                        ? request.meta.parentAgentId
-                        : agentId;
-                    const delegationWidgetId =
-                      typeof request.meta?.delegationWidgetId === 'string'
-                        ? request.meta.delegationWidgetId
-                        : undefined;
-                    queuedItems.push({
-                      agentId: targetAgentId,
-                      event: targetEvent,
-                      delegationContext: {
-                        parentAgentId,
-                        toolCallId,
-                        delegationWidgetId,
-                      },
-                    });
-                  }
+                  queuedItems.push({ agentId: targetAgentId, event: targetEvent });
                 }
                 return false;
               }
 
-              if (chunk.type === 'agent:output') {
-                const content = chunk.data?.content;
-                if (typeof content === 'string' && content.trim().length > 0) {
-                  runOutputs.push(content.trim());
-                }
-              }
-
-              // For delegate mode, child agent execution is internal:
-              // capture outputs for parent tool result, but don't stream child events to clients/storage.
-              if (delegationContext) {
-                return false;
-              }
-
               // If we get here, the event is accepted and should be emitted.
               await this.options.onEvent(chunk, state);
               return true;
@@ -191,11 +135,11 @@ export class QueueProcessor {
             await this.options.onEvent(
               {
                 type: 'agent:run:start',
-                data: { 
-                  runId: this.options.runId, 
-                  agentId, 
-                  channelId: this.options.channelId, 
-                  threadId: this.currentThreadId 
+                data: {
+                  runId: this.options.runId,
+                  agentId,
+                  channelId: this.options.channelId,
+                  threadId: this.currentThreadId,
                 },
               },
               startState,
@@ -221,75 +165,42 @@ export class QueueProcessor {
               await this.options.onEvent(
                 {
                   type: 'agent:run:end',
-                  data: { 
-                    runId: this.options.runId, 
-                    agentId, 
-                    channelId: this.options.channelId, 
-                    threadId: this.currentThreadId 
+                  data: {
+                    runId: this.options.runId,
+                    agentId,
+                    channelId: this.options.channelId,
+                    threadId: this.currentThreadId,
                   },
                 },
                 endState,
               );
-            }
 
-            if (delegationContext) {
-              const summary =
-                runOutputs.length > 0
-                  ? runOutputs.join('\n\n').slice(0, 4000)
-                  : `Delegated agent "${agentId}" completed with no textual output.`;
-              
-              const delegateResultEvent: DelegateResultEvent = ensureEventId({
-                type: 'action:delegate:result',
-                data: {
-                  success: true,
-                  agentId,
-                  summary,
-                },
-                meta: {
-                  toolCallId: delegationContext.toolCallId,
-                  agentId: delegationContext.parentAgentId,
+              // Autonomous todo advance: mark this agent's in_progress todo done
+              // and dispatch the next assignee, if any. Single trigger point,
+              // no reliance on the LLM remembering to call `todo_update`.
+              try {
+                const handoff = await advanceAfterRun({
+                  storage: storageService,
+                  channelId: this.options.channelId,
                   threadId: this.currentThreadId,
-                },
-              } satisfies DelegateResultEvent) as DelegateResultEvent;
-
-              if (delegationContext.delegationWidgetId) {
-                await this.options.onEvent(
-                  ensureEventId({
-                    type: 'client:ui:widget',
-                    data: {
-                      kind: 'message',
-                      widgetId: delegationContext.delegationWidgetId,
-                      title: `Delegation complete: ${agentId}`,
-                      body:
-                        runOutputs.length > 0
-                          ? 'Delegated task finished. Parent agent is preparing final response.'
-                          : 'Delegated task finished with no textual output. Parent agent will continue.',
-                      state: 'submitted',
-                      metadata: {
-                        type: 'delegation:status',
-                        phase: 'completed',
-                        delegatedAgentId: agentId,
-                      },
-                    },
-                    meta: {
-                      agentId: delegationContext.parentAgentId,
-                      threadId: this.currentThreadId,
-                    },
-                  } as OpenBotEvent),
-                  await storageService.getOpenBotState({
-                    runId: this.options.runId,
-                    agentId: delegationContext.parentAgentId,
-                    channelId: this.options.channelId,
-                    threadId: this.currentThreadId,
-                    event: delegateResultEvent,
-                  }),
-                );
+                  endedAgentId: agentId,
+                  lastAgentOutput,
+                });
+                if (handoff) {
+                  const requestKey = `handoff:${handoff.agentId}`;
+                  if (!queuedRequestKeys.has(requestKey)) {
+                    queuedRequestKeys.add(requestKey);
+                    const targetEvent = ensureEventId({
+                      type: 'agent:invoke',
+                      data: { role: 'user', content: handoff.content },
+                      meta: { threadId: this.currentThreadId },
+                    } satisfies AgentInvokeEvent) as AgentInvokeEvent;
+                    queuedItems.push({ agentId: handoff.agentId, event: targetEvent });
+                  }
+                }
+              } catch (error) {
+                console.warn('[queue] todo advance failed', error);
               }
-
-              nextQueue.push({
-                agentId: delegationContext.parentAgentId,
-                event: delegateResultEvent,
-              });
             }
 
             nextQueue.push(...queuedItems);

package/src/harness/runtime-factory.ts

@@ -7,8 +7,8 @@ import { busServicesPlugin } from '../bus/services.js';
 
 /**
  * Enhances the agent's instructions with a list of other available agents the
- * orchestrator can hand off / delegate to. Agents that include the
- * `delegation` plugin will surface peers; agents without it can ignore this.
+ * orchestrator can hand off to. Agents that include the `delegation` plugin
+ * will surface peers; agents without it can ignore this.
  */
 export async function enhanceInstructions(state: OpenBotState) {
   const { agentId, agentDetails } = state;
@@ -23,12 +23,16 @@ export async function enhanceInstructions(state: OpenBotState) {
       .map((a) => `- **${a.id}**${a.description ? `: ${a.description}` : ''}`)
       .join('\n');
 
-    const header = '### Available Agents for Handoff/Delegation:';
+    const header = '### Available Agents:';
     if (!agentDetails.instructions.includes(header)) {
-      agentDetails.instructions +=
-        `\n\n${header}\n${agentsList}\n\n` +
-        'Use `handoff` to transfer control to another agent. ' +
-        'Use `delegate` when you need a sub-result from another agent and want to continue after it returns.';
+      const hasHandoff = (agentDetails.pluginRefs || []).some((r) => r.id === 'delegation');
+      const hasTodo = (agentDetails.pluginRefs || []).some((r) => r.id === 'todo');
+      const usage = hasTodo
+        ? 'Use these ids as `assignee` when calling `todo_write` to plan multi-agent work.'
+        : hasHandoff
+          ? 'Use `handoff` to transfer control to another agent in this thread.'
+          : '';
+      agentDetails.instructions += `\n\n${header}\n${agentsList}${usage ? `\n\n${usage}` : ''}`;
     }
   } catch (error) {
     console.warn('[agent] Failed to enhance instructions', error);