@providerprotocol/agents 0.0.2 → 0.0.4

package/src/execution/types.ts

@@ -1,315 +0,0 @@
-import type {
-  LLMInstance,
-  Message,
-  Tool,
-  Turn,
-  ToolCall,
-  ToolExecution,
-  StreamEvent,
-  TokenUsage,
-} from '@providerprotocol/ai';
-import type { AgentState, PlanStep } from '../state/index.ts';
-import type { CheckpointStore } from '../checkpoint/types.ts';
-
-/**
- * Result of agent generation.
- */
-export interface GenerateResult {
-  /** Standard UPP Turn */
-  turn: Turn;
-  /** New immutable state */
-  state: AgentState;
-}
-
-/**
- * Agent lifecycle hooks for execution control.
- */
-export interface AgentStrategy {
-  /** Evaluate if execution should stop */
-  stopCondition?: (state: AgentState) => boolean | Promise<boolean>;
-  /** Called when step begins */
-  onStepStart?: (step: number, state: AgentState) => void;
-  /** Called during reasoning phase (ReAct) */
-  onReason?: (step: number, reasoning: string) => void;
-  /** Called during action phase */
-  onAct?: (step: number, actions: ToolCall[]) => void;
-  /** Called during observation phase */
-  onObserve?: (step: number, observations: ToolExecution[]) => void;
-  /** Called when step completes */
-  onStepEnd?: (step: number, result: { turn: Turn; state: AgentState }) => void;
-  /** Called when execution completes */
-  onComplete?: (result: GenerateResult) => void;
-  /** Called on execution error */
-  onError?: (error: Error, state: AgentState) => void | GenerateResult;
-}
-
-/**
- * Forward declaration of Agent for use in ExecutionContext.
- * The actual Agent interface is defined in agent/types.ts.
- */
-export interface AgentRef {
-  id: string;
-  system?: string;
-}
-
-/**
- * Context passed to execution strategies.
- */
-export interface ExecutionContext {
-  /** The agent being executed */
-  agent: AgentRef;
-  /** The bound LLM instance */
-  llm: LLMInstance;
-  /** The user input message */
-  input: Message;
-  /** Current immutable state */
-  state: AgentState;
-  /** Resolved tools */
-  tools: Tool[];
-  /** Agent lifecycle hooks */
-  strategy: AgentStrategy;
-  /** Abort signal for cancellation */
-  signal?: AbortSignal;
-  /** Checkpoint store for persistence (optional) */
-  checkpoints?: CheckpointStore;
-  /** Session ID for checkpointing */
-  sessionId?: string;
-}
-
-/**
- * Result from execution strategy.
- */
-export interface ExecutionResult {
-  /** The complete UPP Turn */
-  turn: Turn;
-  /** New immutable state */
-  state: AgentState;
-}
-
-/**
- * UAP-level event types for streaming.
- */
-export type UAPEventType =
-  | 'step_start'
-  | 'step_end'
-  | 'reasoning'
-  | 'action'
-  | 'observation'
-  | 'plan_created'
-  | 'plan_step_start'
-  | 'plan_step_end'
-  | 'subagent_start'
-  | 'subagent_event'
-  | 'subagent_end';
-
-/**
- * Agent stream event - wraps both UAP and UPP events.
- */
-export interface AgentStreamEvent {
-  /** Event source */
-  source: 'uap' | 'upp';
-
-  /** Present when source === 'uap' */
-  uap?: {
-    type: UAPEventType;
-    step: number;
-    agentId: string;
-    data: Record<string, unknown>;
-  };
-
-  /** Present when source === 'upp' */
-  upp?: StreamEvent;
-}
-
-/**
- * Streaming result from agent execution.
- */
-export interface AgentStreamResult {
-  /** Async iterator for stream events */
-  [Symbol.asyncIterator](): AsyncIterator<AgentStreamEvent>;
-  /** Resolves to final result after stream completes */
-  result: Promise<GenerateResult>;
-  /** Abort the stream */
-  abort(): void;
-}
-
-/**
- * Execution strategy interface.
- * Strategies define HOW an agent executes (loop, react, plan).
- */
-export interface ExecutionStrategy {
-  /** Strategy name */
-  name: string;
-  /** Execute the strategy */
-  execute(context: ExecutionContext): Promise<ExecutionResult>;
-  /** Execute with streaming */
-  stream(context: ExecutionContext): AgentStreamResult;
-}
-
-/**
- * Options for loop() strategy.
- */
-export interface LoopOptions {
-  /** Maximum tool execution rounds. Default: Infinity */
-  maxIterations?: number;
-}
-
-/**
- * Options for react() strategy.
- */
-export interface ReactOptions {
-  /** Maximum reason-act-observe cycles. Default: Infinity */
-  maxSteps?: number;
-  /** Prompt suffix for reasoning phase */
-  reasoningPrompt?: string;
-}
-
-/**
- * Options for plan() strategy.
- */
-export interface PlanOptions {
-  /** Maximum steps in a plan. Default: Infinity */
-  maxPlanSteps?: number;
-  /** Allow replanning on failure. Default: true */
-  allowReplan?: boolean;
-  /** Schema for plan structure */
-  planSchema?: Record<string, unknown>;
-}
-
-/**
- * Internal plan structure used by plan() strategy.
- */
-export interface ExecutionPlan {
-  steps: PlanStep[];
-  currentStepIndex: number;
-}
-
-/**
- * Tool dependency options for execution ordering.
- * These extend the base UPP Tool interface with UAP-specific fields.
- *
- * @see UAP-1.0 Spec Section 8.5
- */
-export interface ToolDependencyOptions {
-  /**
-   * If true, this tool must complete before other tools start.
-   * Sequential tools create a barrier in parallel execution.
-   */
-  sequential?: boolean;
-  /**
-   * Tool names that must complete before this tool can execute.
-   * Used for explicit dependency chains.
-   */
-  dependsOn?: string[];
-}
-
-/**
- * Extended Tool interface with UAP dependency options.
- * Use this type when defining tools that need execution ordering.
- *
- * @example
- * ```typescript
- * const readTool: ToolWithDependencies = {
- *   name: 'read_file',
- *   description: 'Read a file',
- *   parameters: { ... },
- *   sequential: true, // Must complete before other tools
- *   run: async (params) => { ... },
- * };
- *
- * const writeTool: ToolWithDependencies = {
- *   name: 'write_file',
- *   description: 'Write a file',
- *   parameters: { ... },
- *   dependsOn: ['read_file'], // Waits for read_file to complete
- *   run: async (params) => { ... },
- * };
- * ```
- */
-export interface ToolWithDependencies extends Tool, ToolDependencyOptions {}
-
-/**
- * Model-driven tool call with optional execution order hint.
- * Models MAY include an `after` field to signal dependencies.
- *
- * @see UAP-1.0 Spec Section 8.6
- */
-export interface OrderedToolCall extends ToolCall {
-  /** Tool call IDs that must complete before this call executes */
-  after?: string[];
-}
-
-/**
- * Sub-agent event types for hierarchical agent execution.
- *
- * @see UAP-1.0 Spec Section 8.7
- */
-export type SubagentEventType = 'subagent_start' | 'subagent_event' | 'subagent_end';
-
-/**
- * Base fields present in all subagent events.
- */
-export interface SubagentEventBase {
-  /** Unique ID of the sub-agent instance */
-  subagentId: string;
-  /** Type/name of the sub-agent (e.g., "explorer", "planner") */
-  subagentType: string;
-  /** The parent tool call ID that spawned this sub-agent */
-  parentToolCallId: string;
-}
-
-/**
- * Event emitted when a sub-agent starts execution.
- */
-export interface SubagentStartEvent extends SubagentEventBase {
-  type: 'subagent_start';
-  /** The task/prompt given to the sub-agent */
-  prompt: string;
-  /** Start timestamp in milliseconds */
-  timestamp: number;
-}
-
-/**
- * Event emitted for forwarded events from sub-agent execution.
- */
-export interface SubagentInnerEvent extends SubagentEventBase {
-  type: 'subagent_event';
-  /** The actual event from the sub-agent */
-  innerEvent: AgentStreamEvent;
-}
-
-/**
- * Event emitted when a sub-agent completes execution.
- */
-export interface SubagentEndEvent extends SubagentEventBase {
-  type: 'subagent_end';
-  /** Whether the sub-agent completed successfully */
-  success: boolean;
-  /** Sub-agent's response text (if successful) */
-  result?: string;
-  /** Error message (if failed) */
-  error?: string;
-  /** End timestamp in milliseconds */
-  timestamp: number;
-  /** Tools used by the sub-agent */
-  toolExecutions?: Array<{
-    toolName: string;
-    arguments: Record<string, unknown>;
-    result: string;
-  }>;
-  /** Token usage for this sub-agent run */
-  usage?: TokenUsage;
-}
-
-/**
- * Union type for all sub-agent events.
- *
- * @see UAP-1.0 Spec Section 8.7
- */
-export type SubagentEvent = SubagentStartEvent | SubagentInnerEvent | SubagentEndEvent;
-
-/**
- * Callback type for receiving sub-agent events.
- * Tools that spawn sub-agents SHOULD accept this callback.
- */
-export type OnSubagentEvent = (event: SubagentEvent) => void;

package/src/index.ts

@@ -1,80 +0,0 @@
-/**
- * @providerprotocol/agents - Unified Agent Protocol (UAP) 1.0 Implementation
- *
- * UAP provides agent abstractions built on @providerprotocol/ai (UPP-1.2):
- * - Functional state management with immutable AgentState
- * - Decoupled execution strategies (loop, react, plan)
- * - Middleware pipeline for cross-cutting concerns
- * - Thread trees for branching conversations
- *
- * Core Philosophy: "UAP is a pipe, not a nanny."
- * The protocol provides orchestration primitives; the developer provides the constraints.
- *
- * @example
- * ```typescript
- * import { agent, AgentState } from '@providerprotocol/agents';
- * import { react } from '@providerprotocol/agents/execution';
- * import { logging } from '@providerprotocol/agents/middleware';
- * import { anthropic } from '@providerprotocol/ai/anthropic';
- *
- * const coder = agent({
- *   model: anthropic('claude-sonnet-4-20250514'),
- *   execution: react(),
- *   tools: [Bash, Read, Write],
- *   system: 'You are an expert software engineer.',
- *   middleware: [logging({ level: 'info' })],
- * });
- *
- * const state = AgentState.initial();
- * const { turn, state: newState } = await coder.generate('Fix the bug', state);
- * console.log(turn.response.text);
- * ```
- *
- * @packageDocumentation
- */
-
-// Main exports
-export { agent } from './agent/index.ts';
-export { AgentState } from './state/index.ts';
-
-// Type exports from agent
-export type {
-  Agent,
-  AgentOptions,
-  GenerateResult,
-  AgentStreamResult,
-  AgentStreamEvent,
-  UAPEventType,
-  AgentStrategy,
-  // Sub-agent event types (Section 8.7)
-  SubagentEventType,
-  SubagentEventBase,
-  SubagentStartEvent,
-  SubagentInnerEvent,
-  SubagentEndEvent,
-  SubagentEvent,
-  OnSubagentEvent,
-} from './agent/index.ts';
-
-// Type exports from state
-export type {
-  AgentStateInterface,
-  AgentStateJSON,
-  PlanStep,
-  PlanStepStatus,
-  SubagentExecutionTrace,
-  SubagentExecutionTraceJSON,
-  ToolExecutionTrace,
-} from './state/index.ts';
-
-// Thread tree exports (Level 3 - optional)
-export { ThreadTree, ThreadNode } from './thread-tree/index.ts';
-export type { ThreadTreeJSON, ThreadNodeJSON } from './thread-tree/index.ts';
-
-// Checkpoint exports (Section 12.4)
-export type {
-  CheckpointStore,
-  FileCheckpointOptions,
-  CheckpointMetadata,
-  CheckpointData,
-} from './checkpoint/index.ts';

package/src/middleware/index.ts

@@ -1,7 +0,0 @@
-export { logging } from './logging.ts';
-
-export type {
-  Middleware,
-  MiddlewareContext,
-  LoggingOptions,
-} from './types.ts';

package/src/middleware/logging.ts

@@ -1,123 +0,0 @@
-import type { Middleware, LoggingOptions, MiddlewareContext } from './types.ts';
-import type { GenerateResult } from '../execution/types.ts';
-
-const DEFAULT_LOGGING_OPTIONS: Required<LoggingOptions> = {
-  level: 'info',
-  logger: console.log,
-  includeMessages: false,
-  includeTiming: true,
-};
-
-const LOG_LEVELS = {
-  debug: 0,
-  info: 1,
-  warn: 2,
-  error: 3,
-} as const;
-
-/**
- * Create a logging middleware.
- *
- * Logs agent execution with configurable detail level:
- * - Execution start/end
- * - Timing information (if enabled)
- * - Message content (if enabled)
- * - Errors
- *
- * @param options - Logging configuration options
- * @returns Middleware
- */
-export function logging(options: LoggingOptions = {}): Middleware {
-  const opts = { ...DEFAULT_LOGGING_OPTIONS, ...options };
-  const currentLevel = LOG_LEVELS[opts.level];
-
-  function shouldLog(level: keyof typeof LOG_LEVELS): boolean {
-    return LOG_LEVELS[level] >= currentLevel;
-  }
-
-  function log(level: keyof typeof LOG_LEVELS, message: string): void {
-    if (shouldLog(level)) {
-      const prefix = `[UAP:${level.toUpperCase()}]`;
-      opts.logger(`${prefix} ${message}`);
-    }
-  }
-
-  function formatContext(context: MiddlewareContext): string {
-    const parts = [`agent=${context.agent.id}`];
-
-    if (opts.includeMessages) {
-      parts.push(`messages=${context.state.messages.length}`);
-    }
-
-    return parts.join(' ');
-  }
-
-  return {
-    name: 'logging',
-
-    async before(context: MiddlewareContext): Promise<MiddlewareContext | void> {
-      log('info', `Execution started: ${formatContext(context)}`);
-
-      if (opts.includeTiming) {
-        context.metadata.set('_logging_startTime', Date.now());
-      }
-
-      if (opts.includeMessages && shouldLog('debug')) {
-        log('debug', `Input: ${JSON.stringify(context.input)}`);
-      }
-
-      return context;
-    },
-
-    async after(
-      context: MiddlewareContext,
-      result: GenerateResult,
-    ): Promise<GenerateResult> {
-      let message = 'Execution completed';
-
-      if (opts.includeTiming) {
-        const startTime = context.metadata.get('_logging_startTime') as number | undefined;
-        if (startTime) {
-          const duration = Date.now() - startTime;
-          message += ` in ${duration}ms`;
-        }
-      }
-
-      message += `: ${formatContext(context)}`;
-
-      if (result.turn.usage) {
-        message += ` tokens=${result.turn.usage.totalTokens}`;
-      }
-
-      log('info', message);
-
-      if (opts.includeMessages && shouldLog('debug')) {
-        log('debug', `Response: ${result.turn.response.text.substring(0, 200)}...`);
-      }
-
-      return result;
-    },
-
-    async onError(
-      context: MiddlewareContext,
-      error: Error,
-    ): Promise<GenerateResult | void> {
-      let message = `Execution failed: ${error.message}`;
-
-      if (opts.includeTiming) {
-        const startTime = context.metadata.get('_logging_startTime') as number | undefined;
-        if (startTime) {
-          const duration = Date.now() - startTime;
-          message += ` after ${duration}ms`;
-        }
-      }
-
-      message += `: ${formatContext(context)}`;
-
-      log('error', message);
-
-      // Let the error propagate
-      return undefined;
-    },
-  };
-}

package/src/middleware/types.ts

@@ -1,69 +0,0 @@
-import type { Message } from '@providerprotocol/ai';
-import type { AgentState } from '../state/index.ts';
-import type { GenerateResult } from '../execution/types.ts';
-
-/**
- * Forward declaration of Agent for use in MiddlewareContext.
- */
-export interface AgentRef {
-  id: string;
-  system?: string;
-}
-
-/**
- * Context passed to middleware functions.
- */
-export interface MiddlewareContext {
-  /** The agent being executed */
-  agent: AgentRef;
-  /** User input message */
-  input: Message;
-  /** Current state */
-  state: AgentState;
-  /** Request metadata (mutable within middleware) */
-  metadata: Map<string, unknown>;
-}
-
-/**
- * Middleware interface for cross-cutting concerns.
- *
- * Middleware executes in order for `before`, reverse order for `after`:
- * - before: first -> second -> third
- * - after: third -> second -> first
- */
-export interface Middleware {
-  /** Middleware name */
-  name: string;
-
-  /**
-   * Called before agent execution.
-   * Can modify context or short-circuit by returning a modified context.
-   */
-  before?(context: MiddlewareContext): Promise<MiddlewareContext | void>;
-
-  /**
-   * Called after agent execution.
-   * Can modify the result before returning.
-   */
-  after?(context: MiddlewareContext, result: GenerateResult): Promise<GenerateResult>;
-
-  /**
-   * Called when an error occurs during execution.
-   * Can return a result to recover, or void to let the error propagate.
-   */
-  onError?(context: MiddlewareContext, error: Error): Promise<GenerateResult | void>;
-}
-
-/**
- * Options for the logging middleware.
- */
-export interface LoggingOptions {
-  /** Log level. Default: 'info' */
-  level?: 'debug' | 'info' | 'warn' | 'error';
-  /** Custom logger function. Default: console.log */
-  logger?: (message: string) => void;
-  /** Include full message content. Default: false */
-  includeMessages?: boolean;
-  /** Include execution timing. Default: true */
-  includeTiming?: boolean;
-}