@providerprotocol/agents 0.0.2 → 0.0.4

package/src/execution/react.ts

@@ -1,340 +0,0 @@
-import type { Turn, StreamEvent } from '@providerprotocol/ai';
-import { UserMessage } from '@providerprotocol/ai';
-import type {
-  ExecutionStrategy,
-  ExecutionContext,
-  ExecutionResult,
-  ReactOptions,
-  AgentStreamResult,
-  AgentStreamEvent,
-} from './types.ts';
-
-const DEFAULT_REACT_OPTIONS: Required<ReactOptions> = {
-  maxSteps: Infinity,
-  reasoningPrompt: 'Think step by step about what you need to do next. Consider the current state, what tools are available, and what action would be most helpful.',
-};
-
-/**
- * Create a ReAct (Reason-Act-Observe) execution strategy.
- *
- * Behavior:
- * 1. Reason: LLM outputs reasoning about what to do next
- * 2. Act: LLM selects and executes tool(s)
- * 3. Observe: Tool results are formatted as observations
- * 4. Repeat until stop condition, no more actions, or maxSteps
- *
- * @param options - ReAct configuration options
- * @returns ExecutionStrategy
- */
-export function react(options: ReactOptions = {}): ExecutionStrategy {
-  const opts = { ...DEFAULT_REACT_OPTIONS, ...options };
-
-  return {
-    name: 'react',
-
-    async execute(context: ExecutionContext): Promise<ExecutionResult> {
-      const { llm, input, state, strategy, signal } = context;
-
-      // Add input message to state and set agentId in metadata
-      // This ensures checkpoints include the full conversation
-      let currentState = state
-        .withMessage(input)
-        .withMetadata('agentId', context.agent.id);
-      let step = 0;
-      let finalTurn: Turn | undefined;
-
-      // Messages for LLM generation (includes input we just added)
-      const messages = [...currentState.messages];
-
-      while (true) {
-        step++;
-        currentState = currentState.withStep(step);
-
-        if (signal?.aborted) {
-          throw new Error('Execution aborted');
-        }
-
-        strategy.onStepStart?.(step, currentState);
-
-        // REASON PHASE: Ask LLM to think about what to do
-        const reasoningMessages = [
-          ...messages,
-          new UserMessage(opts.reasoningPrompt),
-        ];
-
-        const reasoningTurn = await llm.generate(reasoningMessages);
-
-        const reasoning = reasoningTurn.response.text;
-        currentState = currentState.withReasoning(reasoning);
-        strategy.onReason?.(step, reasoning);
-
-        // Add reasoning to conversation
-        messages.push(...reasoningTurn.messages);
-
-        // ACT PHASE: Execute with tools
-        const actionPrompt = new UserMessage(
-          'Based on your reasoning, take the appropriate action. Use tools if needed, or provide a final answer.',
-        );
-        messages.push(actionPrompt);
-
-        const actionTurn = await llm.generate(messages);
-        finalTurn = actionTurn;
-
-        // Update messages with action response
-        messages.push(...actionTurn.messages);
-        currentState = currentState.withMessages(actionTurn.messages);
-
-        // Handle tool calls
-        if (actionTurn.response.hasToolCalls) {
-          strategy.onAct?.(step, actionTurn.response.toolCalls ?? []);
-        }
-
-        // OBSERVE PHASE: Process tool results
-        if (actionTurn.toolExecutions && actionTurn.toolExecutions.length > 0) {
-          strategy.onObserve?.(step, actionTurn.toolExecutions);
-        }
-
-        strategy.onStepEnd?.(step, { turn: actionTurn, state: currentState });
-
-        // Check stop conditions
-        const shouldStop = await strategy.stopCondition?.(currentState);
-        if (shouldStop) {
-          break;
-        }
-
-        // No more tool calls means we're done
-        if (!actionTurn.response.hasToolCalls) {
-          break;
-        }
-
-        // Check step limit
-        if (opts.maxSteps !== Infinity && step >= opts.maxSteps) {
-          break;
-        }
-      }
-
-      if (!finalTurn) {
-        throw new Error('No turn generated');
-      }
-
-      // Include sessionId in state metadata if checkpointing is enabled
-      let finalState = currentState;
-      if (context.sessionId) {
-        finalState = currentState.withMetadata('sessionId', context.sessionId);
-      }
-
-      const result: ExecutionResult = {
-        turn: finalTurn,
-        state: finalState,
-      };
-
-      strategy.onComplete?.(result);
-
-      return result;
-    },
-
-    stream(context: ExecutionContext): AgentStreamResult {
-      const { llm, input, state, strategy, signal } = context;
-      const agentId = context.agent.id;
-
-      let aborted = false;
-      const abortController = new AbortController();
-
-      if (signal) {
-        signal.addEventListener('abort', () => abortController.abort());
-      }
-
-      let resolveResult: (result: ExecutionResult) => void;
-      let rejectResult: (error: Error) => void;
-
-      const resultPromise = new Promise<ExecutionResult>((resolve, reject) => {
-        resolveResult = resolve;
-        rejectResult = reject;
-      });
-
-      async function* generateEvents(): AsyncGenerator<AgentStreamEvent> {
-        // Add input message to state and set agentId in metadata
-        // This ensures checkpoints include the full conversation
-        let currentState = state
-          .withMessage(input)
-          .withMetadata('agentId', context.agent.id);
-        let step = 0;
-        let finalTurn: Turn | undefined;
-
-        // Messages for LLM generation (includes input we just added)
-        const messages = [...currentState.messages];
-
-        try {
-          while (!aborted) {
-            step++;
-            currentState = currentState.withStep(step);
-
-            if (abortController.signal.aborted) {
-              throw new Error('Execution aborted');
-            }
-
-            strategy.onStepStart?.(step, currentState);
-
-            yield {
-              source: 'uap',
-              uap: {
-                type: 'step_start',
-                step,
-                agentId,
-                data: { phase: 'reasoning' },
-              },
-            };
-
-            // REASON PHASE
-            const reasoningMessages = [
-              ...messages,
-              new UserMessage(opts.reasoningPrompt),
-            ];
-
-            const reasoningStream = llm.stream(reasoningMessages);
-            let reasoningText = '';
-
-            for await (const event of reasoningStream as AsyncIterable<StreamEvent>) {
-              if (abortController.signal.aborted) {
-                throw new Error('Execution aborted');
-              }
-
-              yield { source: 'upp', upp: event };
-
-              if (event.type === 'text_delta' && event.delta.text) {
-                reasoningText += event.delta.text;
-              }
-            }
-
-            const reasoningTurn = await reasoningStream.turn;
-            currentState = currentState.withReasoning(reasoningText || reasoningTurn.response.text);
-            strategy.onReason?.(step, reasoningText || reasoningTurn.response.text);
-
-            yield {
-              source: 'uap',
-              uap: {
-                type: 'reasoning',
-                step,
-                agentId,
-                data: { reasoning: reasoningText || reasoningTurn.response.text },
-              },
-            };
-
-            messages.push(...reasoningTurn.messages);
-
-            // ACT PHASE
-            const actionPrompt = new UserMessage(
-              'Based on your reasoning, take the appropriate action. Use tools if needed, or provide a final answer.',
-            );
-            messages.push(actionPrompt);
-
-            const actionStream = llm.stream(messages);
-
-            for await (const event of actionStream as AsyncIterable<StreamEvent>) {
-              if (abortController.signal.aborted) {
-                throw new Error('Execution aborted');
-              }
-
-              yield { source: 'upp', upp: event };
-            }
-
-            const actionTurn = await actionStream.turn;
-            finalTurn = actionTurn;
-
-            messages.push(...actionTurn.messages);
-            currentState = currentState.withMessages(actionTurn.messages);
-
-            if (actionTurn.response.hasToolCalls) {
-              strategy.onAct?.(step, actionTurn.response.toolCalls ?? []);
-
-              yield {
-                source: 'uap',
-                uap: {
-                  type: 'action',
-                  step,
-                  agentId,
-                  data: { toolCalls: actionTurn.response.toolCalls },
-                },
-              };
-            }
-
-            if (actionTurn.toolExecutions && actionTurn.toolExecutions.length > 0) {
-              strategy.onObserve?.(step, actionTurn.toolExecutions);
-
-              yield {
-                source: 'uap',
-                uap: {
-                  type: 'observation',
-                  step,
-                  agentId,
-                  data: { observations: actionTurn.toolExecutions },
-                },
-              };
-            }
-
-            strategy.onStepEnd?.(step, { turn: actionTurn, state: currentState });
-
-            yield {
-              source: 'uap',
-              uap: {
-                type: 'step_end',
-                step,
-                agentId,
-                data: { phase: 'complete' },
-              },
-            };
-
-            const shouldStop = await strategy.stopCondition?.(currentState);
-            if (shouldStop) {
-              break;
-            }
-
-            if (!actionTurn.response.hasToolCalls) {
-              break;
-            }
-
-            if (opts.maxSteps !== Infinity && step >= opts.maxSteps) {
-              break;
-            }
-          }
-
-          if (!finalTurn) {
-            throw new Error('No turn generated');
-          }
-
-          // Include sessionId in state metadata if checkpointing is enabled
-          let finalState = currentState;
-          if (context.sessionId) {
-            finalState = currentState.withMetadata('sessionId', context.sessionId);
-          }
-
-          const result: ExecutionResult = {
-            turn: finalTurn,
-            state: finalState,
-          };
-
-          strategy.onComplete?.(result);
-          resolveResult(result);
-        } catch (error) {
-          const err = error instanceof Error ? error : new Error(String(error));
-          strategy.onError?.(err, currentState);
-          rejectResult(err);
-          throw err;
-        }
-      }
-
-      const iterator = generateEvents();
-
-      return {
-        [Symbol.asyncIterator]() {
-          return iterator;
-        },
-        result: resultPromise,
-        abort() {
-          aborted = true;
-          abortController.abort();
-        },
-      };
-    },
-  };
-}

package/src/execution/tool-ordering.ts

@@ -1,186 +0,0 @@
-import type { Tool, ToolCall } from '@providerprotocol/ai';
-import type { ToolWithDependencies, OrderedToolCall } from './types.ts';
-
-/**
- * Execution group - a set of tool calls that can execute in parallel.
- */
-export interface ExecutionGroup {
-  /** Tool calls in this group */
-  calls: ToolCall[];
-  /** Whether this group contains a sequential tool (acts as barrier) */
-  isBarrier: boolean;
-}
-
-/**
- * Build a map of tool definitions by name for quick lookup.
- */
-function buildToolMap(tools: Tool[]): Map<string, ToolWithDependencies> {
-  const map = new Map<string, ToolWithDependencies>();
-  for (const tool of tools) {
-    map.set(tool.name, tool as ToolWithDependencies);
-  }
-  return map;
-}
-
-/**
- * Check if a tool call has an explicit dependency via model hint.
- */
-function getModelDependencies(call: ToolCall): string[] {
-  const orderedCall = call as OrderedToolCall;
-  return orderedCall.after ?? [];
-}
-
-/**
- * Order tool calls into execution groups respecting dependencies.
- *
- * This function takes a list of tool calls and the available tools,
- * then groups them for execution while respecting:
- * 1. Tool-level `sequential` flag (creates execution barriers)
- * 2. Tool-level `dependsOn` array (tool must wait for named tools)
- * 3. Model-driven `after` array on tool calls (call must wait for specific calls)
- *
- * @param toolCalls - Tool calls from the model response
- * @param tools - Tool definitions (may include dependency options)
- * @returns Ordered array of execution groups
- *
- * @example
- * ```typescript
- * const groups = orderToolCalls(turn.response.toolCalls, agent.tools);
- *
- * for (const group of groups) {
- *   if (group.isBarrier) {
- *     // Execute sequentially
- *     for (const call of group.calls) {
- *       await executeTool(call);
- *     }
- *   } else {
- *     // Execute in parallel
- *     await Promise.all(group.calls.map(executeTool));
- *   }
- * }
- * ```
- */
-export function orderToolCalls(
-  toolCalls: ToolCall[],
-  tools: Tool[],
-): ExecutionGroup[] {
-  if (toolCalls.length === 0) {
-    return [];
-  }
-
-  const toolMap = buildToolMap(tools);
-  const groups: ExecutionGroup[] = [];
-
-  // Track completed tool calls and tool names
-  const completedCallIds = new Set<string>();
-  const completedToolNames = new Set<string>();
-
-  // Create a queue of pending calls
-  const pending = [...toolCalls];
-
-  while (pending.length > 0) {
-    const readyForExecution: ToolCall[] = [];
-    let hasSequential = false;
-
-    // Find all calls that can execute now
-    const stillPending: ToolCall[] = [];
-
-    for (const call of pending) {
-      const tool = toolMap.get(call.toolName);
-      const toolDependsOn = tool?.dependsOn ?? [];
-      const modelDependsOn = getModelDependencies(call);
-
-      // Check if tool-level dependencies are satisfied
-      const toolDepsOk = toolDependsOn.every(
-        (depName) => completedToolNames.has(depName),
-      );
-
-      // Check if model-level dependencies are satisfied
-      const modelDepsOk = modelDependsOn.every(
-        (depId) => completedCallIds.has(depId),
-      );
-
-      if (toolDepsOk && modelDepsOk) {
-        readyForExecution.push(call);
-        if (tool?.sequential) {
-          hasSequential = true;
-        }
-      } else {
-        stillPending.push(call);
-      }
-    }
-
-    // If nothing is ready but we have pending items, there's a cycle
-    if (readyForExecution.length === 0 && stillPending.length > 0) {
-      // Break the cycle by executing remaining items
-      // This is a fallback - ideally dependencies should be acyclic
-      groups.push({
-        calls: stillPending,
-        isBarrier: false,
-      });
-      break;
-    }
-
-    // If we have sequential tools, they form a barrier
-    // Process them one at a time
-    if (hasSequential) {
-      for (const call of readyForExecution) {
-        const tool = toolMap.get(call.toolName);
-        groups.push({
-          calls: [call],
-          isBarrier: tool?.sequential ?? false,
-        });
-        completedCallIds.add(call.toolCallId);
-        completedToolNames.add(call.toolName);
-      }
-    } else {
-      // Non-sequential tools can be grouped for parallel execution
-      groups.push({
-        calls: readyForExecution,
-        isBarrier: false,
-      });
-      for (const call of readyForExecution) {
-        completedCallIds.add(call.toolCallId);
-        completedToolNames.add(call.toolName);
-      }
-    }
-
-    // Update pending list
-    pending.length = 0;
-    pending.push(...stillPending);
-  }
-
-  return groups;
-}
-
-/**
- * Check if any tools have execution dependencies defined.
- *
- * @param tools - Tool definitions to check
- * @returns true if any tool has sequential or dependsOn set
- */
-export function hasToolDependencies(tools: Tool[]): boolean {
-  for (const tool of tools) {
-    const t = tool as ToolWithDependencies;
-    if (t.sequential || (t.dependsOn && t.dependsOn.length > 0)) {
-      return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Check if any tool calls have model-driven dependencies.
- *
- * @param toolCalls - Tool calls to check
- * @returns true if any call has the `after` field set
- */
-export function hasCallDependencies(toolCalls: ToolCall[]): boolean {
-  for (const call of toolCalls) {
-    const ordered = call as OrderedToolCall;
-    if (ordered.after && ordered.after.length > 0) {
-      return true;
-    }
-  }
-  return false;
-}